LocationView

LocationView é um widget que exibe dados de GPS como texto: latitude e longitude (em graus/minutos/segundos com sufixos N/S e E/W), hora do fix, velocidade, direção e número de satélites. Ele lê periodicamente de uma Location (fonte de GPS — porta COM/Bluetooth/IR ou APIs nativas) e atualiza cinco Labels empilhados num VerticalLayout.

Ele não desenha mapa — apenas mostra os números. Para centralizar um mapa na posição do dispositivo, use Map (ver Cap. 25).

🟡 · Pacote: dev.crossfly.ui · Estende: Component · Fonte de dados: dev.crossfly.device.Location

Quando usar

• Mostrar as coordenadas atuais do dispositivo em texto (diagnóstico, HUD, tela de status de GPS).
• Ter uma leitura periódica automática de posição sem escrever o loop de timer.

Quando NÃO usar

• Renderizar um mapa ou marcar a posição visualmente → use Map (Cap. 25).
• Só ler a posição uma vez em código, sem UI → use a classe Location diretamente.

Aparência

Cinco linhas de texto (lat, lon, fix, speed, direction), alinhadas à esquerda, num VerticalLayout. Enquanto não há dados exibe “Location Initialising”; sem sinal, exibe as strings localizáveis LAT_LOW_SIGNAL / LON_LOW_SIGNAL.

Exemplo completo (copiar, colar e rodar)

LocationView é um componente comum: entra direto na tela com add(LAY_AUTO, ...). O construtor declara throws IOException, já coberto pelo onShow() throws Exception. O timer inicia no onAdd e para no onRemove — não é preciso gerenciá-lo manualmente.

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** Tela principal executável. Aponte o launcher (classname) e rode: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      add(LAY_AUTO, new Label("Coordenadas do GPS:"));

      LocationView gps = new LocationView(1000);   // lê a cada 1 s; throws IOException
      gps.onAction(c -> {}); // disparado a cada leitura periódica (opcional)
      add(LAY_AUTO, gps);
      // O timer inicia no onAdd e para no onRemove automaticamente.
   }
}

Os trechos abaixo mostram só o miolo (o que vai dentro de onShow()). Para rodar, coloque-os no esqueleto MainWindow acima.

Uso básico

LocationView gps = new LocationView(1000);   // lê a cada 1 s; throws IOException
container.add(LAY_AUTO, gps);
// Ao sair da tela, o onRemove já para o timer; ou chame gps.stop().

Construtores

Propriedades e personalização

Callbacks e eventos

Estados

• inicializando: antes do primeiro fix, mostra “Location Initialising”.
• com sinal: exibe lat/lon em graus/minutos/segundos, hora do fix (formato 12/24 h vem de LocaleFormats.is24Hour), velocidade/direção quando != Location.INVALID e satélites quando > 0.
• sem sinal: exibe LAT_LOW_SIGNAL / LON_LOW_SIGNAL e a razão da falha na última linha.
• ciclo de vida: o timer inicia em onAdd e é parado em onRemove (ou por stop()), liberando recursos.

Fonte de GPS explícita + reação a cada atualização

Location fonte = /* obtida da plataforma / dev.crossfly.device */;
LocationView gps = new LocationView(fonte, 1000);
gps.onAction(c -> atualizarStatusBarra());  // disparado a cada leitura
container.add(LAY_AUTO, gps);

// Localizar as mensagens de baixo sinal:
LocationView.LAT_LOW_SIGNAL = "lat: sem sinal";
LocationView.LON_LOW_SIGNAL = "lon: sem sinal";

Boas práticas

• Deixe o ciclo de vida cuidar do timer: adicionar o widget o inicia, removê-lo o para. Chame stop() explicitamente só se precisar liberar a Location antes.
• Ajuste readInterval conforme a necessidade — intervalos menores gastam mais bateria; o mínimo efetivo é 100 ms.

Erros comuns

• Esquecer o throws IOException dos construtores.
• Esperar um mapa: LocationView só mostra texto; para visualização use Map.
• Assumir a hora local sem timezone: o fix é ajustado pelo offset do fuso via TimeZone.getDefault().getRawOffset().

Veja também

• Guia da área: ui/ · Receitas: cookbook/
• Conceito (i18n, formatos de locale): concepts/
• Componentes relacionados: webcontainer