# Examples

The `examples/` directory contains runnable Dear PyGui programs:

```bash
uv run python examples/basic_map.py
uv run python examples/custom_provider.py
uv run python examples/cache_stress.py
uv run python examples/markers_live_thread.py
uv run python examples/trajectory_live_thread.py
uv run python examples/sizing_window.py
uv run python examples/sizing_child.py
uv run python examples/sizing_table.py
uv run python examples/hidden_tab.py
```

## Basic Map

Creates one map and one marker.

```python
with dpg.window(label="Map", width=-1, height=-1):
    with dpgm.map_widget(tag="map", center=(47.9029, 1.9093), zoom=15, width=-1, height=-1):
        dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093)
```

Run:

```bash
uv run python examples/basic_map.py
```

## Live Marker Updates

Use explicit `map_tag` from background threads or callbacks.

```python
dpgm.add_marker("vehicle", lat=47.9029, lon=1.9093, map_tag="map")

def update_from_telemetry(lat: float, lon: float) -> None:
    dpgm.update_marker("vehicle", lat=lat, lon=lon, map_tag="map")
```

Run a threaded stress example:

```bash
uv run python examples/markers_live_thread.py
```

## Live Trajectory

Keep an application-owned point buffer and pass immutable snapshots to `update_trajectory(...)`.

```python
points: list[tuple[float, float]] = []
dpgm.add_trajectory("track", points=[], show_points=True, point_stride=12, map_tag="map")

def push_point(lat: float, lon: float) -> None:
    points.append((lat, lon))
    dpgm.update_trajectory("track", points=tuple(points), map_tag="map")
```

Run:

```bash
uv run python examples/trajectory_live_thread.py
```

## Multiple Maps

Each map is independent. Reusing overlay tags across different maps is valid, but runtime updates
should pass `map_tag` to avoid ambiguity.

```python
with dpgm.map_widget(tag="live-map", center=(47.9, 1.9), zoom=15, width=-1, height=300):
    dpgm.add_marker("vehicle", lat=47.9, lon=1.9)

with dpgm.map_widget(tag="recap-map", center=(47.9, 1.9), zoom=13, width=-1, height=300):
    dpgm.add_trajectory("vehicle", points=[])

dpgm.update_marker("vehicle", lat=47.901, lon=1.902, map_tag="live-map")
dpgm.update_trajectory("vehicle", points=lap_points, map_tag="recap-map")
```

## Custom Provider Switch

Register a provider, create the map with it, and switch at runtime.

```python
carto = dpgm.TileProvider(
    name="carto-light",
    url_template="https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png",
    subdomains=("a", "b", "c", "d"),
    attribution="(c) OpenStreetMap contributors (c) CARTO",
)

dpgm.register_provider(carto)
dpgm.set_provider("carto-light", map_tag="map")
dpgm.set_provider("osm", map_tag="map")
```

Run:

```bash
uv run python examples/custom_provider.py
```

## Cache Controls

Configure a local cache and expose buttons in your UI.

```python
dpgm.configure(cache_dir=".tile-cache", memory_cache_max_tiles=128)

def clear_memory() -> None:
    dpgm.clear_memory_cache(map_tag="map")

def clear_disk() -> None:
    dpgm.clear_disk_cache(map_tag="map")

def refresh_stats() -> str:
    stats = dpgm.get_cache_stats(map_tag="map")
    return f"{stats.memory_tiles} memory tiles, {stats.disk_bytes} disk bytes"
```

Run:

```bash
uv run python examples/cache_stress.py
```

## Layout And Sizing

The widget works inside windows, child windows, tables, and hidden tabs.

```python
with dpg.child_window(width=-1, height=420):
    with dpgm.map_widget(tag="map-child", width=-1, height=-1):
        dpgm.add_marker("inside-child", lat=47.0, lon=2.0)
```

Run:

```bash
uv run python examples/sizing_child.py
```