# Getting Started with Java Leaflet

This guide will help you get up and running with Java Leaflet in minutes, whether you're building a JavaFX desktop application or a Vaadin web application.

## Table of Contents

- [Installation](#installation)
  - [JavaFX Setup](#javafx-setup)
  - [Vaadin Setup](#vaadin-setup)
- [Creating Your First Map](#creating-your-first-map)
  - [JavaFX Example](#javafx-example)
  - [Vaadin Example](#vaadin-example)
- [Basic Concepts](#basic-concepts)
- [Next Steps](#next-steps)

---

## Installation

### Prerequisites

- **Java 17** or higher
- **Maven 3.6+** or Gradle 7+
- For JavaFX: **JavaFX SDK 19+**
- For Vaadin: **Node.js 16+** (for frontend compilation)

### JavaFX Setup

Add the JavaFX dependency to your `pom.xml`:

```xml
<dependencies>
    <!-- Java Leaflet for JavaFX -->
    <dependency>
        <groupId>io.github.makbn</groupId>
        <artifactId>jlmap-fx</artifactId>
        <version>2.0.0</version>
    </dependency>
</dependencies>
```

If using Gradle:

```gradle
dependencies {
    implementation 'io.github.makbn:jlmap-fx:2.0.0'
}
```

### Vaadin Setup

For Vaadin applications, add the Vaadin dependency:

```xml
<dependencies>
    <!-- Java Leaflet for Vaadin -->
    <dependency>
        <groupId>io.github.makbn</groupId>
        <artifactId>jlmap-vaadin</artifactId>
        <version>2.0.0</version>
    </dependency>

    <!-- Vaadin Spring Boot Starter (if using Spring Boot) -->
    <dependency>
        <groupId>com.vaadin</groupId>
        <artifactId>vaadin-spring-boot-starter</artifactId>
        <version>24.8.6</version>
    </dependency>
</dependencies>
```

---

## Creating Your First Map

### JavaFX Example

Create a simple JavaFX application with an interactive map:

```java
package com.example;

import io.github.makbn.jlmap.fx.JLMapView;
import io.github.makbn.jlmap.map.JLMapProvider;
import io.github.makbn.jlmap.model.JLLatLng;
import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.layout.BorderPane;
import javafx.stage.Stage;

public class MyFirstMap extends Application {

    @Override
    public void start(Stage primaryStage) {
        // Create the map view
        JLMapView mapView = JLMapView.builder()
                .jlMapProvider(JLMapProvider.OSM_MAPNIK.build())
                .startCoordinate(new JLLatLng(51.505, -0.09)) // London
                .showZoomController(true)
                .build();

        // Create the scene
        BorderPane root = new BorderPane(mapView);
        Scene scene = new Scene(root, 800, 600);

        // Configure the stage
        primaryStage.setTitle("My First Java Leaflet Map");
        primaryStage.setScene(scene);
        primaryStage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}
```

**Run the application:**

```bash
mvn javafx:run
```

### Vaadin Example

Create a Vaadin view with an interactive map:

```java
package com.example.views;

import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;
import io.github.makbn.jlmap.map.JLMapProvider;
import io.github.makbn.jlmap.model.JLLatLng;
import io.github.makbn.jlmap.vaadin.JLMapView;

@Route("")
public class MainView extends VerticalLayout {

    public MainView() {
        setSizeFull();
        setPadding(false);

        // Create the map view
        JLMapView mapView = JLMapView.builder()
                .jlMapProvider(JLMapProvider.OSM_MAPNIK.build())
                .startCoordinate(new JLLatLng(48.864716, 2.349014)) // Paris
                .showZoomController(true)
                .build();

        mapView.setSizeFull();
        add(mapView);
    }
}
```

**Run the application:**

```bash
mvn spring-boot:run
```

Then open [http://localhost:8080](http://localhost:8080) in your browser.

---

## Basic Concepts

### 1. Map Providers

Java Leaflet supports multiple tile providers:

```java
// OpenStreetMap Mapnik (default)
JLMapProvider.OSM_MAPNIK.build()

// MapTiler (requires API key)
JLMapProvider.MAP_TILER
    .parameter(new JLMapOption.Parameter("key", "YOUR_API_KEY"))
    .build()

// Water Color
JLMapProvider.WATER_COLOR
    .parameter(new JLMapOption.Parameter("key", "YOUR_API_KEY"))
    .build()
```

### 2. Adding Markers

Add interactive markers to your map:

```java
// After map is loaded
mapView.getUiLayer().addMarker(
    new JLLatLng(51.505, -0.09),
    "Hello London!",
    true  // draggable
);
```

### 3. Layer System

Java Leaflet organizes functionality into four main layers:

```java
// UI Layer - markers, popups, images
mapView.getUiLayer().addMarker(...);

// Vector Layer - polygons, polylines, circles
mapView.getVectorLayer().addCircle(...);

// Control Layer - zoom, pan, bounds
mapView.getControlLayer().setZoom(12);

// GeoJSON Layer - GeoJSON data
mapView.getGeoJsonLayer().addFromFile(...);
```

### 4. Event Handling

Respond to user interactions:

```java
JLMarker marker = mapView.getUiLayer().addMarker(...);

marker.setOnActionListener((source, event) -> {
    if (event instanceof ClickEvent clickEvent) {
        System.out.println("Marker clicked at: " + clickEvent.center());
    }
});
```

---

## Adding More Features

### Adding a Popup

```java
JLPopup popup = mapView.getUiLayer().addPopup(
    new JLLatLng(51.5, -0.09),
    "<h3>Hello!</h3><p>This is a popup</p>"
);
```

### Drawing Shapes

```java
// Draw a circle
mapView.getVectorLayer().addCircle(
    new JLLatLng(51.508, -0.11),
    500,  // radius in meters
    JLOptions.builder()
        .color(JLColor.BLUE)
        .fillColor(JLColor.BLUE)
        .fillOpacity(0.3)
        .build()
);

// Draw a polygon
JLLatLng[] vertices = {
    new JLLatLng(51.509, -0.08),
    new JLLatLng(51.503, -0.06),
    new JLLatLng(51.51, -0.047)
};

mapView.getVectorLayer().addPolygon(
    new JLLatLng[][][] { new JLLatLng[][] { vertices } },
    JLOptions.builder()
        .color(JLColor.RED)
        .build()
);
```

### Controlling the View

```java
// Pan to a location
mapView.getControlLayer().panTo(new JLLatLng(51.505, -0.09));

// Animate to a location
mapView.getControlLayer().flyTo(new JLLatLng(48.8566, 2.3522), 10);

// Zoom
mapView.getControlLayer().zoomIn(2);
mapView.getControlLayer().setZoom(12);

// Fit bounds
JLBounds bounds = JLBounds.builder()
    .southWest(new JLLatLng(51.5, -0.1))
    .northEast(new JLLatLng(51.52, -0.08))
    .build();
mapView.getControlLayer().fitBounds(bounds);
```

---

## Complete Example

Here's a more complete example showing multiple features:

```java
import io.github.makbn.jlmap.fx.JLMapView;
import io.github.makbn.jlmap.map.JLMapProvider;
import io.github.makbn.jlmap.model.*;
import io.github.makbn.jlmap.listener.event.ClickEvent;
import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.layout.BorderPane;
import javafx.stage.Stage;

public class ComprehensiveExample extends Application {

    @Override
    public void start(Stage primaryStage) {
        // Create map
        JLMapView mapView = JLMapView.builder()
                .jlMapProvider(JLMapProvider.OSM_MAPNIK.build())
                .startCoordinate(new JLLatLng(51.505, -0.09))
                .showZoomController(true)
                .build();

        // Add a marker with popup
        JLMarker marker = mapView.getUiLayer().addMarker(
            new JLLatLng(51.505, -0.09),
            "Click me!",
            true
        );

        // Add click listener
        marker.setOnActionListener((source, event) -> {
            if (event instanceof ClickEvent) {
                System.out.println("Marker clicked!");
            }
        });

        // Draw a circle around the marker
        mapView.getVectorLayer().addCircle(
            new JLLatLng(51.505, -0.09),
            500,
            JLOptions.builder()
                .color(JLColor.BLUE)
                .fillOpacity(0.2)
                .build()
        );

        // Create scene
        BorderPane root = new BorderPane(mapView);
        Scene scene = new Scene(root, 1000, 700);

        primaryStage.setTitle("Java Leaflet - Comprehensive Example");
        primaryStage.setScene(scene);
        primaryStage.show();
    }

    public static void main(String[] args) {
        launch(args);
    }
}
```

---

## Troubleshooting

### JavaFX: Map Not Showing

If the map doesn't appear:

1. **Check JavaFX modules** - Ensure JavaFX modules are in your module path
2. **Wait for map load** - The map loads asynchronously. Use event listeners if needed
3. **Check console** - Look for JavaScript errors in the console

### Vaadin: Compilation Errors

If you get frontend compilation errors:

1. **Install Node.js** - Vaadin requires Node.js for frontend compilation
2. **Run `mvn clean install`** - This will download and install frontend dependencies
3. **Check Vaadin version** - Ensure you're using Vaadin 24+

### Module Path Issues

If you encounter module issues:

```java
module com.example.myapp {
    requires io.github.makbn.jlmap.fx;  // For JavaFX
    // OR
    requires io.github.makbn.jlmap.vaadin;  // For Vaadin

    requires javafx.controls;  // For JavaFX
    requires javafx.web;       // For JavaFX
}
```

---

## Next Steps

Now that you have a basic map running, explore more features:

1. **[Context Menus](Context-Menu-Guide)** - Add right-click menus to map objects
2. **[Journey System](Journey-System)** - Create animated journeys
3. **[API Reference](API-Reference)** - Explore the complete API
4. **[Examples & Tutorials](Examples-and-Tutorials)** - Learn from more examples
5. **[Architecture](Architecture)** - Understand the internals

---

## Additional Resources

- **[JavaFX Documentation](https://openjfx.io/)** - Learn more about JavaFX
- **[Vaadin Documentation](https://vaadin.com/docs)** - Learn more about Vaadin
- **[Leaflet.js](https://leafletjs.com/)** - Original JavaScript library
- **[GitHub Repository](https://github.com/makbn/java_leaflet)** - Source code and examples

---

**Previous**: [← Home](Home) | **Next**: [Architecture Overview →](Architecture)