LocationView

LocationView 是一个以文本形式显示 GPS 数据的组件：纬度和经度（以度/分/秒表示，带 N/S 和 E/W 后缀）、定位时间、速度、方向和卫星数量。它周期性地从一个 Location（GPS 源 —— COM 端口/蓝牙/红外，或原生 API）读取数据，并更新在 VerticalLayout 中堆叠的五个 Label。

它不绘制地图 —— 只显示数字。若要将地图居中到设备位置，请使用 Map（参见第 25 章）。

🟡 · 包： dev.crossfly.ui · 继承自： Component · 数据源： dev.crossfly.device.Location

何时使用

以文本显示设备当前坐标（诊断、HUD、GPS 状态屏）。
需要自动周期性读取位置，而无需编写定时器循环。

何时不要使用

渲染地图或以可视方式标记位置 → 使用 Map（第 25 章）。
只在代码中读取一次位置，不涉及 UI → 直接使用 Location 类。

外观

五行文本（纬度、经度、定位、速度、方向），左对齐，位于一个 VerticalLayout 中。在没有数据时显示 “Location Initialising”；无信号时显示可本地化的字符串 LAT_LOW_SIGNAL / LON_LOW_SIGNAL。

完整示例（复制、粘贴并运行）

LocationView 是一个普通组件：用 add(LAY_AUTO, ...) 直接放入屏幕。构造函数声明了 throws IOException，已由 onShow() throws Exception 覆盖。定时器在 onAdd 中启动、在 onRemove 中停止 —— 无需手动管理。

package com.exemplo;

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

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：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);   // 每 1 秒读取一次；throws IOException
      gps.onAction(c -> {}); // 每次周期性读取时触发（可选）
      add(LAY_AUTO, gps);
      // 定时器在 onAdd 中启动，在 onRemove 中自动停止。
   }
}

下面的片段只展示核心部分（放在 onShow() 里的内容）。要运行它们，请放入上面的 MainWindow 骨架中。

基本用法

LocationView gps = new LocationView(1000);   // 每 1 秒读取一次；throws IOException
container.add(LAY_AUTO, gps);
// 离开界面时，onRemove 已停止定时器；或调用 gps.stop()。

构造函数

构造函数	描述
`LocationView()`	读取间隔 2000 毫秒，`location = null`。`throws IOException`。
`LocationView(int readInterval)`	自定义间隔（毫秒；有效最小值 100），`location = null`。`throws IOException`。
`LocationView(Location location, int readInterval)`	显式指定 GPS 源 + 间隔。`throws IOException`。

属性与自定义

方法 / 字段	类型	作用
`location`	`Location`（字段）	GPS 数据源；可在构造函数中传入或保持 `null`。
`stop()`	`void`	停止定时器并调用 `location.stop()`。`throws IOException`。
`retrieveGPSData()`	`void`	读取位置并更新标签（由定时器调用）。
`getAutoHeight()`	`int`	首选高度 = `font.scaledHeight() * 5 + ingap.height()`。
`LocationView.LAT_LOW_SIGNAL`	静态 `String`	无法获取纬度时显示的文本（可本地化）。
`LocationView.LON_LOW_SIGNAL`	静态 `String`	无法获取经度时显示的文本（可本地化）。

回调与事件

回调	触发时机
`onAction(Action)`	每次周期性读取时（`retrieveGPSData()` 调用 `runActions()`），无论是否有信号。可作为更新通知点使用。

状态

初始化中：在首次定位之前，显示 “Location Initialising”。
有信号：以度/分/秒显示纬度/经度，显示定位时间（12/24 小时格式来自 LocaleFormats.is24Hour），当 != Location.INVALID 时显示速度/方向，当 > 0 时显示卫星数。
无信号：在最后一行显示 LAT_LOW_SIGNAL / LON_LOW_SIGNAL 及失败原因。
生命周期：定时器在 onAdd 中启动，在 onRemove 中停止（或通过 stop()），并释放资源。

显式 GPS 源 + 对每次更新做出响应

Location fonte = /* 从平台获取 / dev.crossfly.device */;
LocationView gps = new LocationView(fonte, 1000);
gps.onAction(c -> atualizarStatusBarra());  // 每次读取时触发
container.add(LAY_AUTO, gps);

// 定位低信号消息：
LocationView.LAT_LOW_SIGNAL = "lat: sem sinal";
LocationView.LON_LOW_SIGNAL = "lon: sem sinal";

最佳实践

让生命周期来管理定时器：添加组件即启动它，移除它即停止。仅在需要提前释放 Location 时才显式调用 stop()。
根据需要调整 readInterval —— 更短的间隔更耗电；有效最小值为 100 毫秒。

常见错误

忘记构造函数的 throws IOException。
期望出现地图：LocationView 只显示文本；如需可视化请使用 Map。
在没有时区的情况下假设本地时间：定位时间通过 TimeZone.getDefault().getRawOffset() 按时区偏移进行调整。

另请参阅

领域指南：ui/ · 实用配方：cookbook/
概念（i18n、locale 格式）：concepts/
相关组件：webcontainer