+ * This interface provides a consistent abstraction layer for map operations in both JavaFX and Vaadin + * implementations, allowing developers to write framework-agnostic mapping code. + *
+ *+ * The interface provides access to various layers (UI, Vector, Control, GeoJSON) and map manipulation + * methods such as view setting, zooming, and retrieving map state information. + *
+ * + * @param+ * The web engine handles the communication between Java code and the Leaflet JavaScript library, + * enabling dynamic map operations and event handling. + *
+ * + * @return the web engine instance specific to the UI framework implementation + */ + JLWebEngine+ * This method sets up the necessary JavaScript infrastructure for map operations, + * including event handlers and communication bridges between Java and JavaScript layers. + *
+ *+ * Typically called internally during map initialization and should not be invoked manually. + *
+ */ + void addControllerToDocument(); + + /** + * Returns the internal registry of map layers by their class types. + *+ * This method provides access to the underlying layer management system, mapping + * layer interface classes to their concrete implementations. + *
+ *+ * Note: This is primarily for internal use. Access layers through + * the dedicated getter methods instead: {@link #getUiLayer()}, {@link #getVectorLayer()}, + * {@link #getControlLayer()}, {@link #getGeoJsonLayer()}. + *
+ * + * @return a map of layer classes to their instances + */ + HashMap+ * The UI layer handles user interface elements that appear above the map content, + * including markers with custom icons, popups with HTML content, and image overlays. + *
+ * + * @return the UI layer interface for adding and managing user interface elements + * @throws JLMapNotReadyException if the map is not properly initialized + */ + default LeafletUILayerInt getUiLayer() { + checkMapState(); + return getLayerInternal(LeafletUILayerInt.class); + } + + /** + * Provides access to the vector layer for managing geometric shapes and paths. + *+ * The vector layer handles geometric elements such as circles, polygons, polylines, + * and other vectorial shapes that can be styled and made interactive. + *
+ * + * @return the vector layer interface for adding and managing geometric shapes + * @throws JLMapNotReadyException if the map is not properly initialized + */ + default LeafletVectorLayerInt getVectorLayer() { + checkMapState(); + return getLayerInternal(LeafletVectorLayerInt.class); + } + + /** + * Provides access to the control layer for map navigation and view management. + *+ * The control layer handles map manipulation operations such as zooming, panning, + * setting bounds, and controlling the map's viewport and navigation state. + *
+ * + * @return the control layer interface for map navigation and view control + * @throws JLMapNotReadyException if the map is not properly initialized + */ + default LeafletControlLayerInt getControlLayer() { + checkMapState(); + return getLayerInternal(LeafletControlLayerInt.class); + } + + /** + * Provides access to the GeoJSON layer for managing geographic data layers. + *+ * The GeoJSON layer handles the loading, styling, and interaction with GeoJSON + * geographic data, supporting both simple displays and advanced features like + * custom styling functions and data filtering. + *
+ * + * @return the GeoJSON layer interface for managing geographic data + * @throws JLMapNotReadyException if the map is not properly initialized + */ + default LeafletGeoJsonLayerInt getGeoJsonLayer() { + checkMapState(); + return getLayerInternal(LeafletGeoJsonLayerInt.class); + } + + + /** + * Smoothly pans the map view to the specified geographical coordinates. + *+ * This method performs an animated transition to center the map on the given location + * while maintaining the current zoom level. The pan operation uses the default + * animation duration and easing settings. + *
+ * + * @param latLng the target geographical coordinates to pan to + * @throws JLMapNotReadyException if the map is not properly initialized + */ + default void setView(JLLatLng latLng) { + checkMapState(); + getJLEngine() + .executeScript(String.format("this.map.panTo([%f, %f]);", + latLng.getLat(), latLng.getLng())); + } + + /** + * Smoothly pans the map view to the specified geographical coordinates with custom animation duration. + *+ * This method performs an animated transition to center the map on the given location + * while maintaining the current zoom level, using the specified animation duration. + *
+ * + * @param latLng the target geographical coordinates to pan to + * @param duration the animation duration in milliseconds + * @throws JLMapNotReadyException if the map is not properly initialized + */ + default void setView(JLLatLng latLng, int duration) { + checkMapState(); + getJLEngine() + .executeScript(String.format("this.map.panTo([%f, %f], %d);", + latLng.getLat(), latLng.getLng(), duration)); + } + + /** + * Retrieves the current zoom level of the map. + *+ * Zoom levels typically range from 0 (world view) to 18+ (building level detail), + * depending on the tile provider. Each zoom level represents a doubling of the scale. + *
+ * + * @return the current zoom level as an integer + * @throws JLMapNotReadyException if the map is not properly initialized + */ + default int getZoom() { + checkMapState(); + Object result = getJLEngine() + .executeScript("this.map.getZoom();"); + return Integer.parseInt(result.toString()); + } + + /** + * Sets the zoom level of the map with animation. + *+ * This method smoothly animates the map to the specified zoom level. + * Zoom levels typically range from 0 (world view) to 18+ (building level detail). + * Values outside the supported range will be clamped to valid bounds. + *
+ * + * @param zoomLevel the target zoom level (typically 0-19) + * @throws JLMapNotReadyException if the map is not properly initialized + */ + default void setZoom(int zoomLevel) { + checkMapState(); + getJLEngine() + .executeScript(String.format("this.map.setZoom(%d);", zoomLevel)); + } + + /** + * Retrieves the current center coordinates of the map view. + *+ * This method returns the geographical coordinates (latitude and longitude) + * that correspond to the center point of the current map viewport. + *
+ * + * @return the center coordinates as a {@link JLLatLng} object + * @throws JLMapNotReadyException if the map is not properly initialized + * @throws NumberFormatException if the coordinate parsing fails + */ + default JLLatLng getCenter() { + checkMapState(); + Object result = getJLEngine() + .executeScript("this.map.getCenter();"); + String[] coords = result.toString().split(","); + double lat = Double.parseDouble(coords[0].trim()); + double lng = Double.parseDouble(coords[1].trim()); + return new JLLatLng(lat, lng); + } + + /** + * Checks if the map is ready for operations. + * + * @throws JLMapNotReadyException if the map is not ready + */ + default void checkMapState() { + if (getJLEngine() == null) { + throw new JLMapNotReadyException("Map engine is not initialized"); + } + } + + private @Nullable+ * The context menu provides a platform-independent way to add interactive menus + * to map elements. It uses mediators to handle platform-specific implementations + * while maintaining a consistent API across different UI frameworks (JavaFX, Vaadin). + *
+ *{@code
+ * JLMarker marker = JLMarker.builder()
+ * .latLng(new JLLatLng(51.5, -0.09))
+ * .build();
+ *
+ * JLContextMenu menu = marker.getContextMenu();
+ * menu.addItem("Edit", "edit-icon")
+ * .addItem("Delete", "delete-icon")
+ * .addItem("Info", "info-icon")
+ * .setOnMenuItemListener(item -> {
+ * switch (item.getId()) {
+ * case "Edit" -> editMarker(marker);
+ * case "Delete" -> deleteMarker(marker);
+ * case "Info" -> showMarkerInfo(marker);
+ * }
+ * });
+ * }
+ *
+ * @param + * Creates a new menu item with the given text and an auto-generated ID. + * The ID will be derived from the text by removing spaces and converting + * to lowercase for consistent identification. + *
+ * + * @param text the display text for the menu item + * @return this context menu instance for method chaining + * @throws IllegalArgumentException if text is null or empty + */ + @NonNull + public JLContextMenu+ * Creates a new menu item with the given ID and display text. + * If a menu item with the same ID already exists, it will be replaced. + *
+ * + * @param id unique identifier for the menu item + * @param text display text for the menu item + * @return this context menu instance for method chaining + * @throws IllegalArgumentException if id or text is null or empty + */ + @NonNull + public JLContextMenu+ * Creates a new menu item with all primary properties specified. + * If a menu item with the same ID already exists, it will be replaced. + *
+ * + * @param id unique identifier for the menu item + * @param text display text for the menu item + * @param icon icon or image reference for the menu item + * @return this context menu instance for method chaining + * @throws IllegalArgumentException if id or text is null or empty + */ + @NonNull + public JLContextMenu+ * Allows adding fully configured menu items with custom properties. + * If a menu item with the same ID already exists, it will be replaced. + *
+ * + * @param item the menu item to add + * @return this context menu instance for method chaining + * @throws IllegalArgumentException if item is null + */ + @NonNull + public JLContextMenu+ * If no menu item exists with the given ID, this method has no effect. + *
+ * + * @param id the ID of the menu item to remove + * @return this context menu instance for method chaining + */ + @NonNull + public JLContextMenu+ * After calling this method, the context menu will be empty and + * will not be displayed until new items are added. + *
+ * + * @return this context menu instance for method chaining + */ + @NonNull + public JLContextMenu+ * Returns the menu item with the specified ID, or null if no such + * item exists in the context menu. + *
+ * + * @param id the ID of the menu item to retrieve + * @return the menu item with the specified ID, or null if not found + */ + public JLMenuItem getItem(@NonNull String id) { + return menuItems.get(id); + } + + /** + * Updates an existing menu item with new properties. + *+ * Finds the menu item with the matching ID and replaces it with the + * updated version. If no item exists with the given ID, the new item + * will be added to the menu. + *
+ * + * @param updatedItem the updated menu item + * @return this context menu instance for method chaining + * @throws IllegalArgumentException if updatedItem is null + */ + @NonNull + public JLContextMenu+ * The returned collection reflects the current state of the menu items + * and will be updated as items are added or removed. However, the + * collection itself cannot be modified directly. + *
+ * + * @return an unmodifiable collection of all menu items + */ + @NonNull + public Collection+ * Filters the menu items to include only those that are marked as visible. + * This is useful for determining what items should actually be displayed + * to the user. + *
+ * + * @return an unmodifiable collection of visible menu items + */ + @NonNull + public Collection+ * Returns true if there is at least one menu item that is marked as visible. + * This is useful for determining whether the context menu should be displayed. + *
+ * + * @return true if there are visible menu items, false otherwise + */ + public boolean hasVisibleItems() { + return menuItems.values().stream().anyMatch(JLMenuItem::isVisible); + } + + /** + * Returns the number of menu items in the context menu. + *+ * Includes both visible and hidden items in the count. + *
+ * + * @return the total number of menu items + */ + public int getItemCount() { + return menuItems.size(); + } + + /** + * Returns the number of visible menu items in the context menu. + *+ * Counts only the items that are marked as visible. + *
+ * + * @return the number of visible menu items + */ + public int getVisibleItemCount() { + return (int) menuItems.values().stream().filter(JLMenuItem::isVisible).count(); + } + + /** + * Sets the listener for menu item selection events. + *+ * The listener will be called whenever a user selects a menu item from + * the context menu. Only one listener can be active at a time; setting + * a new listener will replace the previous one. + *
+ * + * @param listener the listener for menu item selection events, or null to remove + * @return this context menu instance for method chaining + */ + @NonNull + public JLContextMenu+ * This method is called internally when a menu item is selected. + * It delegates to the registered menu item listener if one exists. + *
+ *+ * Internal API: This method is intended for use by + * the context menu mediator implementations and should not be called + * directly by application code. + *
+ * + * @param selectedItem the menu item that was selected + */ + public void handleMenuItemSelection(@NonNull JLMenuItem selectedItem) { + if (onMenuItemListener != null) { + onMenuItemListener.onMenuItemSelected(selectedItem); + } + } + + /** + * Handles context menu lifecycle events. + *+ * This method is called when the context menu is opened or closed, + * allowing the owner object to respond to these events through its + * OnJLActionListener. + *
+ *+ * Internal API: This method is intended for use by + * the context menu mediator implementations and should not be called + * directly by application code. + *
+ * + * @param event the context menu event (open/close) + */ + public void handleContextMenuEvent(@NonNull Event event) { + OnJLActionListener+ * This method is called internally whenever menu items are added, removed, + * or modified. It can be used by mediator implementations to refresh + * the display or update platform-specific menu representations. + *
+ *+ * Internal API: This method is intended for use by + * the context menu mediator implementations and should not be called + * directly by application code. + *
+ */ + protected void notifyMenuUpdated() { + // This method can be overridden by mediator implementations + // to respond to menu changes + } +} diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/element/menu/JLContextMenuMediator.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/element/menu/JLContextMenuMediator.java new file mode 100644 index 0000000..f0ff798 --- /dev/null +++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/element/menu/JLContextMenuMediator.java @@ -0,0 +1,125 @@ +package io.github.makbn.jlmap.element.menu; + +import io.github.makbn.jlmap.JLMap; +import io.github.makbn.jlmap.model.JLObject; +import lombok.NonNull; + +/** + * Platform-independent mediator interface for context menu implementations. + *+ * This interface abstracts the platform-specific context menu implementations + * (JavaFX, Vaadin, etc.) from the common JL context menu API. Each UI framework + * should provide its own implementation of this mediator to handle platform-specific + * menu rendering, event handling, and user interactions. + *
+ *+ * Concrete mediators must: + *
+ *+ * Implementations should be discoverable via Java's ServiceLoader mechanism + * by providing a service configuration file in META-INF/services/. + *
+ *+ * File: META-INF/services/io.github.makbn.jlmap.element.menu.JLContextMenuMediator + * Content: io.github.makbn.jlmap.vaadin.menu.VaadinContextMenuMediator + *+ * + * @author Matt Akbarian (@makbn) + * @since 2.0.0 + */ +public interface JLContextMenuMediator { + + + /** + * Shows the context menu for the specified JL object at the given coordinates. + *
+ * This method is typically called in response to user gestures like right-click + * or long-press. The mediator should display the context menu using platform-specific + * popup or menu components at the specified screen coordinates. + *
+ *+ * Coordinate System: Coordinates are typically relative to + * the map view or screen, depending on the platform implementation. + *
+ * + * @param+ * This method is called when the context menu should be dismissed, either + * programmatically or in response to user actions like clicking outside + * the menu area. + *
+ * + * @param+ * This method allows the service locator to determine which mediator + * should handle a particular JL object. Mediators may support all object + * types or be specialized for specific object categories. + *
+ *+ * This method is useful for debugging, logging, and development tools + * that need to identify which mediator is being used. + *
+ *+ * Names should include the target platform or framework: + *
+ *+ * This interface enables map elements (markers, polygons, polylines, etc.) to have + * context menus that can be displayed when users right-click or long-press on them. + * The context menu is implemented using platform-specific mediators to avoid + * dependency on Leaflet's internal context menu implementation. + *
+ *{@code
+ * JLMarker marker = JLMarker.builder()
+ * .latLng(new JLLatLng(51.5, -0.09))
+ * .build();
+ *
+ * JLContextMenu contextMenu = marker.getContextMenu();
+ * contextMenu.addItem("Edit", "edit-icon")
+ * .addItem("Delete", "delete-icon")
+ * .setOnMenuItemListener(item -> {
+ * switch (item.getId()) {
+ * case "Edit" -> editMarker(marker);
+ * case "Delete" -> marker.remove();
+ * }
+ * });
+ * }
+ *
+ * @param + * Returns the context menu associated with this object. If no context menu + * has been created yet, a new one will be instantiated. The context menu + * allows adding/removing menu items and setting up event listeners. + *
+ *+ * Note: The context menu is created lazily when first accessed. + * This ensures optimal memory usage and performance for objects that may not + * require context menu functionality. + *
+ * + * @return the context menu instance for this object, never null + */ + @Nullable + JLContextMenu+ * Returns true if a context menu exists and contains at least one menu item + * that should be displayed to the user. This is useful for determining + * whether to show context menu indicators or enable right-click functionality. + *
+ *+ * Objects should return false if: + *
+ *+ * Returns true if the context menu will be displayed when users perform + * context menu gestures on this object. A disabled context menu will not + * appear regardless of whether it exists and contains menu items. + *
+ * + * @return true if the context menu is enabled, false otherwise + */ + boolean isContextMenuEnabled(); + + /** + * Enables or disables the context menu for this object. + *+ * Controls whether the context menu should be displayed when users perform + * context menu gestures (right-click, long-press, etc.) on this object. + * When disabled, the context menu will not appear even if it exists and + * contains menu items. + *
+ *+ * Default State: Context menus are enabled by default when created. + *
+ *+ * Each menu item has a unique identifier, display text, optional icon, and can be + * enabled/disabled or shown/hidden. Menu items are immutable once created, promoting + * consistent state management and thread safety. + *
+ *{@code
+ * JLMenuItem editItem = JLMenuItem.builder()
+ * .id("edit")
+ * .text("Edit Properties")
+ * .icon("edit-icon.png")
+ * .enabled(true)
+ * .visible(true)
+ * .build();
+ *
+ * JLMenuItem deleteItem = JLMenuItem.builder()
+ * .id("delete")
+ * .text("Delete Item")
+ * .icon("delete-icon.png")
+ * .enabled(canDelete)
+ * .visible(hasDeletePermission)
+ * .build();
+ * }
+ *
+ * @author Matt Akbarian (@makbn)
+ * @since 2.0.0
+ */
+@Value
+@Builder(toBuilder = true)
+@FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
+public class JLMenuItem {
+
+ /**
+ * Unique identifier for this menu item.
+ * + * The ID is used to identify the menu item when handling selection events + * and for programmatic access. It should be unique within the context menu + * and remain constant throughout the item's lifecycle. + *
+ */ + @NonNull + String id; + + /** + * Display text shown to the user. + *+ * This is the human-readable text that appears in the context menu. + * It should be descriptive and indicate the action that will be performed + * when the menu item is selected. + *
+ */ + @NonNull + String text; + + /** + * Optional icon or image reference for this menu item. + *+ * The icon can be a file path, URL, CSS class name, or any other identifier + * that the underlying UI framework can interpret as an icon. The specific + * format depends on the platform implementation (JavaFX, Vaadin, etc.). + *
+ *+ * Disabled items typically appear grayed out and do not respond to + * click events. They remain visible but cannot be activated. + *
+ *+ * Default: true (enabled) + *
+ */ + @Builder.Default + boolean enabled = true; + + /** + * Whether this menu item is visible in the context menu. + *+ * Hidden items do not appear in the menu at all. This is useful for + * conditionally showing menu items based on user permissions, application + * state, or other dynamic factors. + *
+ *+ * Default: true (visible) + *
+ */ + @Builder.Default + boolean visible = true; + + /** + * Creates a simple menu item with just ID and text. + *+ * This is a convenience factory method for creating basic menu items + * without icons or custom enabled/visible states. + *
+ * + * @param id unique identifier for the menu item + * @param text display text for the menu item + * @return a new menu item instance + */ + public static JLMenuItem of(@NonNull String id, @NonNull String text) { + return JLMenuItem.builder() + .id(id) + .text(text) + .build(); + } + + /** + * Creates a menu item with ID, text, and icon. + *+ * This is a convenience factory method for creating menu items with + * the most commonly used properties. + *
+ * + * @param id unique identifier for the menu item + * @param text display text for the menu item + * @param icon icon or image reference for the menu item + * @return a new menu item instance + */ + public static JLMenuItem of(@NonNull String id, @NonNull String text, String icon) { + return JLMenuItem.builder() + .id(id) + .text(text) + .icon(icon) + .build(); + } +} diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/element/menu/OnJLContextMenuItemListener.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/element/menu/OnJLContextMenuItemListener.java new file mode 100644 index 0000000..e81cd9b --- /dev/null +++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/element/menu/OnJLContextMenuItemListener.java @@ -0,0 +1,37 @@ +package io.github.makbn.jlmap.element.menu; + +/** + * Listener interface for handling context menu item selection events. + *+ * This listener is triggered when a user selects a specific menu item from a context menu. + * It provides the selected menu item to the implementing code for further processing. + *
+ *{@code
+ * JLContextMenu contextMenu = marker.getContextMenu();
+ * contextMenu.setOnMenuItemListener(selectedItem -> {
+ * System.out.println("Selected: " + selectedItem.getText());
+ * if (selectedItem.getId().equals("delete")) {
+ * marker.remove();
+ * }
+ * });
+ * }
+ *
+ * @author Matt Akbarian (@makbn)
+ * @since 2.0.0
+ */
+@FunctionalInterface
+public interface OnJLContextMenuItemListener {
+
+ /**
+ * Called when a menu item is selected from the context menu.
+ * + * This method is invoked whenever a user clicks on a menu item in the context menu. + * The selected menu item is passed as a parameter, allowing the listener to + * determine which action was chosen and respond accordingly. + *
+ * + * @param selectedItem the menu item that was selected by the user + */ + void onMenuItemSelected(JLMenuItem selectedItem); +} \ No newline at end of file diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/engine/JLClientToServerTransporter.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/engine/JLClientToServerTransporter.java new file mode 100644 index 0000000..9b61a84 --- /dev/null +++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/engine/JLClientToServerTransporter.java @@ -0,0 +1,45 @@ +package io.github.makbn.jlmap.engine; + +import io.github.makbn.jlmap.model.JLObject; + +/** + * Generic bridge for JavaScript-to-Java direct method calls on JLObjects. + * This allows JavaScript to call Java methods directly on specific object instances. + * + * @author Matt Akbarian (@makbn) + */ +public interface JLClientToServerTransporter { + + /** + * Calls a method on a specific JLObject instance. + * + * @param objectId The unique identifier of the JLObject + * @param methodName The name of the method to call + * @param args Arguments to pass to the method (JSON serialized) + * @return The result of the method call (JSON serialized), or null for void methods + */ + String callObjectMethod(String objectId, String methodName, String... args); + + /** + * Registers a JLObject so it can be called from JavaScript. + * + * @param objectId Unique identifier for the object + * @param object The JLObject instance + */ + void registerObject(String objectId, JLObject object); + + /** + * Unregisters a JLObject. + * + * @param objectId The unique identifier of the object to remove + */ + void unregisterObject(String objectId); + + /** + * Gets the JavaScript code to inject that enables calling Java methods. + * This should be executed once to set up the bridge. + * + * @return JavaScript code for the bridge + */ + String getJavaScriptBridge(); +} \ No newline at end of file diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/engine/JLClientToServerTransporterBase.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/engine/JLClientToServerTransporterBase.java new file mode 100644 index 0000000..1f14a52 --- /dev/null +++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/engine/JLClientToServerTransporterBase.java @@ -0,0 +1,151 @@ +package io.github.makbn.jlmap.engine; + +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.core.type.TypeReference; +import com.fasterxml.jackson.databind.ObjectMapper; +import io.github.makbn.jlmap.model.JLGeoJson; +import io.github.makbn.jlmap.model.JLObject; +import io.github.makbn.jlmap.model.JLOptions; +import lombok.AccessLevel; +import lombok.NonNull; +import lombok.experimental.FieldDefaults; +import lombok.extern.slf4j.Slf4j; + +import java.util.Collections; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; +import java.util.function.Function; + +/** + * Base implementation of the JLObjectBridge that handles method calling logic. + * Platform-specific implementations extend this to provide the JavaScript integration. + * + * @author Matt Akbarian (@makbn) + */ +@Slf4j +@FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true) +public abstract class JLClientToServerTransporterBase+ * This interface defines the communication bridge between Java objects and the JavaScript + * Leaflet map running in a web view or browser. It enables Java code to execute JavaScript + * functions, modify map elements, and retrieve results asynchronously. + *
+ *+ * The transporter operates as a functional interface that: + *
+ *+ * Concrete implementations handle framework-specific details: + *
+ *{@code
+ * // Void operation (no return value)
+ * JLTransportRequest voidRequest = JLTransportRequest.voidCall(circle, "setRadius", 1000);
+ * transporter.execute(voidRequest); // CompletableFuture
+ *
+ * // Returnable operation (with result)
+ * JLTransportRequest returnRequest = JLTransportRequest.returnableCall(circle, "getBounds", JLBounds.class);
+ * CompletableFuture bounds = transporter.execute(returnRequest);
+ * bounds.thenAccept(b -> System.out.println("Bounds: " + b));
+ * }
+ * + * Thread Safety: Implementations must ensure thread-safe execution, + * typically by marshaling calls to the appropriate UI thread. + *
+ * + * @param+ * This method returns a function that takes a {@link JLTransportRequest} and + * executes the corresponding JavaScript operation, returning the raw result + * in the framework-specific format. + *
+ *+ * Implementation Responsibility: Concrete implementations must: + *
+ *+ * This method handles the conversion from framework-specific raw results + * (e.g., JavaScript objects, JSON values) to strongly-typed Java objects. + * The default implementation throws {@link UnsupportedOperationException} + * and must be overridden by concrete implementations. + *
+ *+ * Implementation Notes: Concrete implementations should: + *
+ *{@code
+ * public CompletableFuture covertResult(Object result, Class clazz) {
+ * try {
+ * if (clazz == String.class) {
+ * return CompletableFuture.completedFuture(clazz.cast(result.toString()));
+ * } else if (clazz == JLBounds.class) {
+ * // Parse bounds from JSON string
+ * return CompletableFuture.completedFuture(clazz.cast(parseBounds(result)));
+ * }
+ * // Handle other types...
+ * } catch (Exception e) {
+ * return CompletableFuture.failedFuture(e);
+ * }
+ * }
+ * }
+ *
+ * @param + * This is the main execution method that coordinates the JavaScript operation + * and result conversion. It handles both void operations (no return value) + * and returnable operations (with typed results). + *
+ *{@code
+ * // Void operation (e.g., setting properties)
+ * JLTransportRequest setRadius = JLTransportRequest.voidCall(circle, "setRadius", 1000);
+ * CompletableFuture voidResult = transporter.execute(setRadius);
+ *
+ * // Returnable operation (e.g., getting values)
+ * JLTransportRequest getBounds = JLTransportRequest.returnableCall(circle, "getBounds", JLBounds.class);
+ * CompletableFuture boundsResult = transporter.execute(getBounds);
+ * boundsResult.thenAccept(bounds -> {
+ * System.out.println("Circle bounds: " + bounds);
+ * });
+ * }
+ * + * Thread Safety: This method must be safe to call from any thread, + * with implementations ensuring JavaScript execution occurs on the appropriate UI thread. + *
+ * + * @param+ * Encapsulates the target object, method name, return type, and parameters for + * JavaScript execution via the transport layer. Supports both void operations + * and typed return values. + *
+ * + * @param self the target JL object for method invocation + * @param function the JavaScript method name to invoke + * @param clazz the expected return type (Void.class for void operations) + * @param params method parameters (converted to JavaScript arguments) + * @author Matt Akbarian (@makbn) + * @since 2.0.0 + */ +public record JLTransportRequest(JLObject self, String function, Class clazz, Object... params) { + + /** + * Creates a void transport request with no return value. + * + * @param self the target object + * @param function the method name + * @param params method parameters + * @return transport request for void operation + */ + public static JLTransportRequest voidCall(@NonNull JLObject self, @NonNull String function, Object... params) { + return new JLTransportRequest(self, function, Void.class, params); + } + + /** + * Creates a returnable transport request with typed return value. + * + * @param self the target object + * @param function the method name + * @param clazz the expected return type + * @param params method parameters + * @return transport request for typed operation + */ + public static JLTransportRequest returnableCall(@NonNull JLObject self, @NonNull String function, Class clazz, Object... params) { + return new JLTransportRequest(self, function, clazz, params); + } + + /** + * Type-safe cast of the return type class. + * + * @param+ * This interface provides methods to manipulate the map's view state, including zoom levels, + * geographic bounds, and animated transitions. All operations are smoothly animated unless + * otherwise specified. + *
+ *+ * The control layer handles the following key operations: + *
+ *+ * Thread Safety: All methods should be called from the UI thread of the + * respective framework (JavaFX Application Thread or Vaadin UI thread). + *
* - * @author Mehdi Akbarian Rastaghi (@makbn) + * @author Matt Akbarian (@makbn) + * @since 2.0.0 */ -public interface LeafletControlLayerInt { +public interface LeafletControlLayerInt extends LeafletLayer { /** - * Increases the zoom of the map by delta + * Smoothly increases the map zoom level by the specified amount. + *+ * The map will animate to the new zoom level while maintaining the current center point. + * If the resulting zoom level exceeds the maximum allowed zoom, it will be clamped. + *
* + * @param delta the number of zoom levels to increase (must be positive) * @see leafletjs.com/reference.html#map-zoomin */ void zoomIn(int delta); /** - * Decreases the zoom of the map by delta + * Smoothly decreases the map zoom level by the specified amount. + *+ * The map will animate to the new zoom level while maintaining the current center point. + * If the resulting zoom level is below the minimum allowed zoom, it will be clamped. + *
* + * @param delta the number of zoom levels to decrease (must be positive) * @see - * leafletjs.com/reference.html#map-zoomout + * leafletjs.com/reference.html#map-zoomout */ void zoomOut(int delta); /** - * Sets the zoom of the map. + * Animates the map to the specified zoom level. + *+ * The map will smoothly transition to the new zoom level while keeping the current + * center point fixed. Values outside the allowed zoom range will be automatically + * clamped to valid bounds. + *
* + * @param level the target zoom level (typically 0-19, depending on tile provider) * @see - * leafletjs.com/reference.html#map-setzoom + * leafletjs.com/reference.html#map-setzoom */ void setZoom(int level); @@ -41,7 +74,7 @@ public interface LeafletControlLayerInt { * stationary (e.g. used internally for scroll zoom and double-click zoom) * * @see - * leafletjs.com/reference.html#map-setzoomaround + * leafletjs.com/reference.html#map-setzoomaround */ void setZoomAround(JLLatLng latLng, int zoom); @@ -52,7 +85,7 @@ public interface LeafletControlLayerInt { * * @param bounds The geographical bounds to fit. * @see - * leafletjs.com/reference.html#map-fitbounds + * leafletjs.com/reference.html#map-fitbounds */ void fitBounds(JLBounds bounds); @@ -61,27 +94,27 @@ public interface LeafletControlLayerInt { * zoom level possible. * * @see - * leafletjs.com/reference.html#map-fitworld + * leafletjs.com/reference.html#map-fitworld */ void fitWorld(); /** - * Pans the map to a given center. + * Pans the map to a given latLng. * - * @param latLng The new center of the map. + * @param latLng The new latLng of the map. * @see - * leafletjs.com/reference.html#map-panto + * leafletjs.com/reference.html#map-panto */ void panTo(JLLatLng latLng); /** - * Sets the view of the map (geographical center and zoom) performing a + * Sets the view of the map (geographical latLng and zoom) performing a * smooth pan-zoom animation. * - * @param latLng The new center of the map. + * @param latLng The new latLng of the map. * @param zoom The new zoom level (optional). * @see - * leafletjs.com/reference.html#map-flyto + * leafletjs.com/reference.html#map-flyto */ void flyTo(JLLatLng latLng, int zoom); @@ -91,7 +124,7 @@ public interface LeafletControlLayerInt { * * @param bounds The bounds to fit the map view to. * @see - * leafletjs.com/reference.html#map-flytobounds + * leafletjs.com/reference.html#map-flytobounds */ void flyToBounds(JLBounds bounds); @@ -100,7 +133,7 @@ public interface LeafletControlLayerInt { * * @param bounds The geographical bounds to restrict the map view to. * @see - * leafletjs.com/reference.html#map-setmaxbounds + * leafletjs.com/reference.html#map-setmaxbounds */ void setMaxBounds(JLBounds bounds); @@ -109,7 +142,7 @@ public interface LeafletControlLayerInt { * * @param zoom The minimum zoom level. * @see - * leafletjs.com/reference.html#map-setminzoom + * leafletjs.com/reference.html#map-setminzoom */ void setMinZoom(int zoom); @@ -118,7 +151,7 @@ public interface LeafletControlLayerInt { * * @param zoom The maximum zoom level. * @see - * leafletjs.com/reference.html#map-setmaxzoom + * leafletjs.com/reference.html#map-setmaxzoom */ void setMaxZoom(int zoom); @@ -127,7 +160,7 @@ public interface LeafletControlLayerInt { * * @param bounds The bounds to pan inside. * @see - * leafletjs.com/reference.html#map-paninsidebounds + * leafletjs.com/reference.html#map-paninsidebounds */ void panInsideBounds(JLBounds bounds); @@ -136,7 +169,7 @@ public interface LeafletControlLayerInt { * * @param latLng The geographical point to make visible. * @see - * leafletjs.com/reference.html#map-paninside + * leafletjs.com/reference.html#map-paninside */ void panInside(JLLatLng latLng); diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletGeoJsonLayerInt.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletGeoJsonLayerInt.java new file mode 100644 index 0000000..95162b4 --- /dev/null +++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletGeoJsonLayerInt.java @@ -0,0 +1,91 @@ +package io.github.makbn.jlmap.layer.leaflet; + +import io.github.makbn.jlmap.exception.JLException; +import io.github.makbn.jlmap.model.JLGeoJson; +import io.github.makbn.jlmap.model.JLGeoJsonOptions; +import lombok.NonNull; + +import java.io.File; + +/** + * The {@code LeafletGeoJsonLayerInt} interface defines methods for adding + * and managing GeoJSON data layers in a Leaflet map. + *+ * Implementations of this interface should provide methods to add GeoJSON + * data from various sources, such as files, URLs, or raw content, as well + * as the ability to remove GeoJSON objects from the map. + *
+ * Enhanced to support advanced GeoJSON features including custom styling,
+ * filtering, and point-to-layer functions.
+ *
+ * @author Matt Akbarian (@makbn)
+ */
+public interface LeafletGeoJsonLayerInt extends LeafletLayer {
+
+ /**
+ * Adds a GeoJSON object from a file to the Leaflet map.
+ *
+ * @param file The {@link File} object representing the GeoJSON file to be added.
+ * @return The {@link JLGeoJson} representing the added GeoJSON data.
+ * @throws JLException If there is an error while adding the GeoJSON data.
+ */
+ JLGeoJson addFromFile(@NonNull File file) throws JLException;
+
+ /**
+ * Adds a GeoJSON object from a file to the Leaflet map with custom options.
+ *
+ * @param file The {@link File} object representing the GeoJSON file to be added.
+ * @param options Custom styling and configuration options for the GeoJSON layer.
+ * @return The {@link JLGeoJson} representing the added GeoJSON data.
+ * @throws JLException If there is an error while adding the GeoJSON data.
+ */
+ JLGeoJson addFromFile(@NonNull File file, @NonNull JLGeoJsonOptions options) throws JLException;
+
+ /**
+ * Adds a GeoJSON object from a URL to the Leaflet map.
+ *
+ * @param url The URL of the GeoJSON data to be added.
+ * @return The {@link JLGeoJson} representing the added GeoJSON data.
+ * @throws JLException If there is an error while adding the GeoJSON data.
+ */
+ JLGeoJson addFromUrl(@NonNull String url) throws JLException;
+
+ /**
+ * Adds a GeoJSON object from a URL to the Leaflet map with custom options.
+ *
+ * @param url The URL of the GeoJSON data to be added.
+ * @param options Custom styling and configuration options for the GeoJSON layer.
+ * @return The {@link JLGeoJson} representing the added GeoJSON data.
+ * @throws JLException If there is an error while adding the GeoJSON data.
+ */
+ JLGeoJson addFromUrl(@NonNull String url, @NonNull JLGeoJsonOptions options) throws JLException;
+
+ /**
+ * Adds a GeoJSON object from raw content to the Leaflet map.
+ *
+ * @param content The raw GeoJSON content to be added.
+ * @return The {@link JLGeoJson} representing the added GeoJSON data.
+ * @throws JLException If there is an error while adding the GeoJSON data.
+ */
+ JLGeoJson addFromContent(@NonNull String content) throws JLException;
+
+ /**
+ * Adds a GeoJSON object from raw content to the Leaflet map with custom options.
+ *
+ * @param content The raw GeoJSON content to be added.
+ * @param options Custom styling and configuration options for the GeoJSON layer.
+ * @return The {@link JLGeoJson} representing the added GeoJSON data.
+ * @throws JLException If there is an error while adding the GeoJSON data.
+ */
+ JLGeoJson addFromContent(@NonNull String content, @NonNull JLGeoJsonOptions options) throws JLException;
+
+ /**
+ * Removes a GeoJSON object from the Leaflet map.
+ *
+ * @param id of the {@link JLGeoJson} to be removed from the map.
+ * @return {@code true} if the removal was successful, {@code false}
+ * if the object was not found or could not be removed.
+ */
+ boolean removeGeoJson(@NonNull String id);
+
+}
diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletLayer.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletLayer.java
new file mode 100644
index 0000000..b8b943c
--- /dev/null
+++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletLayer.java
@@ -0,0 +1,4 @@
+package io.github.makbn.jlmap.layer.leaflet;
+
+public interface LeafletLayer {
+}
diff --git a/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletUILayerInt.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletUILayerInt.java
similarity index 66%
rename from src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletUILayerInt.java
rename to jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletUILayerInt.java
index 394412f..4be9b79 100644
--- a/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletUILayerInt.java
+++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletUILayerInt.java
@@ -1,9 +1,6 @@
package io.github.makbn.jlmap.layer.leaflet;
-import io.github.makbn.jlmap.model.JLLatLng;
-import io.github.makbn.jlmap.model.JLMarker;
-import io.github.makbn.jlmap.model.JLOptions;
-import io.github.makbn.jlmap.model.JLPopup;
+import io.github.makbn.jlmap.model.*;
/**
* The {@code LeafletUILayerInt} interface defines methods for adding and
@@ -12,17 +9,17 @@
* and this interface provides a Java API for working with user interface
* elements within Leaflet.
*
- * @author Mehdi Akbarian Rastaghi (@makbn)
+ * @author Matt Akbarian (@makbn)
*/
-public interface LeafletUILayerInt {
+public interface LeafletUILayerInt extends LeafletLayer {
/**
* Adds a marker to the Leaflet map at the specified geographical
* coordinates.
*
- * @param latLng The geographical coordinates (latitude and longitude)
- * where the marker should be placed.
- * @param text The text content associated with the marker.
+ * @param latLng The geographical coordinates (latitude and longitude)
+ * where the marker should be placed.
+ * @param text The text content associated with the marker.
* @param draggable {@code true} if the marker should be draggable,
* {@code false} otherwise.
* @return The {@link JLMarker} representing the added marker on the map.
@@ -35,9 +32,8 @@ public interface LeafletUILayerInt {
* @param id The unique identifier of the marker to be removed.
* @return {@code true} if the marker was successfully removed,
* {@code false} if the marker with the specified identifier was not found.
- *
*/
- boolean removeMarker(int id);
+ boolean removeMarker(String id);
/**
* Adds a popup to the Leaflet map at the specified geographical
@@ -68,9 +64,20 @@ public interface LeafletUILayerInt {
*
* @param id The unique identifier of the popup to be removed.
* @return {@code true} if the popup was successfully removed,
- * {@code false} if the popup with the specified identifier
- * was not found.
+ * {@code false} if the popup with the specified identifier
+ * was not found.
+ */
+ boolean removePopup(String id);
+
+ /**
+ * Instantiates an image overlay object given the URL of the image and the geographical bounds it is tied to.
+ * Read more about it on Leaflet ImageOverlay
+ *
+ * @param bounds the geographical bounds the image is tied to.
+ * @param imageUrl URL of the image to be used as an overlay. (can be local or remote URL)
+ * @param options theming options for JLImageOverlay. all options are not available!
+ * @return The {@link JLImageOverlay} representing the added image overlay on the map.
*/
- boolean removePopup(int id);
+ JLImageOverlay addImage(JLBounds bounds, String imageUrl, JLOptions options);
}
diff --git a/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletVectorLayerInt.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletVectorLayerInt.java
similarity index 90%
rename from src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletVectorLayerInt.java
rename to jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletVectorLayerInt.java
index 0655f13..ef3d0ac 100644
--- a/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletVectorLayerInt.java
+++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/layer/leaflet/LeafletVectorLayerInt.java
@@ -8,9 +8,9 @@
* Leaflet map. Leaflet is a popular JavaScript library for creating interactive maps, and
* this interface provides a Java API for working with vector-based layers within Leaflet.
*
- * @author Mehdi Akbarian Rastaghi (@makbn)
+ * @author Matt Akbarian (@makbn)
*/
-public interface LeafletVectorLayerInt {
+public interface LeafletVectorLayerInt extends LeafletLayer{
/**
* Adds a polyline to the Leaflet map with the provided array of vertices.
@@ -39,7 +39,7 @@ public interface LeafletVectorLayerInt {
* polyline with the specified identifier was not found.
*/
- boolean removePolyline(int id);
+ boolean removePolyline(String id);
/**
* Adds a multi-polyline to the Leaflet map with the provided array of arrays of vertices.
@@ -67,7 +67,7 @@ public interface LeafletVectorLayerInt {
* @return {@code true} if the multi-polyline was successfully removed, {@code false} if the
* multi-polyline with the specified identifier was not found.
*/
- boolean removeMultiPolyline(int id);
+ boolean removeMultiPolyline(String id);
/**
* Adds a polygon to the Leaflet map with the provided array of arrays of vertices and custom options.
@@ -95,12 +95,12 @@ public interface LeafletVectorLayerInt {
* @return {@code true} if the polygon was successfully removed, {@code false} if the
* polygon with the specified identifier was not found.
*/
- boolean removePolygon(int id);
+ boolean removePolygon(String id);
/**
- * Adds a circle to the Leaflet map with the provided center coordinates, radius, and custom options.
+ * Adds a circle to the Leaflet map with the provided latLng coordinates, radius, and custom options.
*
- * @param center The geographical coordinates (latitude and longitude) of the circle's center.
+ * @param center The geographical coordinates (latitude and longitude) of the circle's latLng.
* @param radius The radius of the circle in meters.
* @param options Custom options for configuring the appearance and behavior of the circle.
* @return The {@link JLCircle} representing the added circle on the map.
@@ -108,9 +108,9 @@ public interface LeafletVectorLayerInt {
JLCircle addCircle(JLLatLng center, int radius, JLOptions options);
/**
- * Adds a circle to the Leaflet map with the provided center coordinates and radius.
+ * Adds a circle to the Leaflet map with the provided latLng coordinates and radius.
*
- * @param center The geographical coordinates (latitude and longitude) of the circle's center.
+ * @param center The geographical coordinates (latitude and longitude) of the circle's latLng.
* @return The {@link JLCircle} representing the added circle on the map.
*/
JLCircle addCircle(JLLatLng center);
@@ -122,12 +122,12 @@ public interface LeafletVectorLayerInt {
* @return {@code true} if the circle was successfully removed, {@code false} if the
* circle with the specified identifier was not found.
*/
- boolean removeCircle(int id);
+ boolean removeCircle(String id);
/**
- * Adds a circle marker to the Leaflet map with the provided center coordinates, radius, and custom options.
+ * Adds a circle marker to the Leaflet map with the provided latLng coordinates, radius, and custom options.
*
- * @param center The geographical coordinates (latitude and longitude) of the circle marker's center.
+ * @param center The geographical coordinates (latitude and longitude) of the circle marker's latLng.
* @param radius The radius of the circle marker in pixels.
* @param options Custom options for configuring the appearance and behavior of the circle marker.
* @return The {@link JLCircleMarker} representing the added circle marker on the map.
@@ -135,9 +135,9 @@ public interface LeafletVectorLayerInt {
JLCircleMarker addCircleMarker(JLLatLng center, int radius, JLOptions options);
/**
- * Adds a circle marker to the Leaflet map with the provided center coordinates and radius.
+ * Adds a circle marker to the Leaflet map with the provided latLng coordinates and radius.
*
- * @param center The geographical coordinates (latitude and longitude) of the circle marker's center.
+ * @param center The geographical coordinates (latitude and longitude) of the circle marker's latLng.
* @return The {@link JLCircleMarker} representing the added circle marker on the map.
*/
JLCircleMarker addCircleMarker(JLLatLng center);
@@ -149,6 +149,6 @@ public interface LeafletVectorLayerInt {
* @return {@code true} if the circle marker was successfully removed, {@code false} if the
* circle marker with the specified identifier was not found.
*/
- boolean removeCircleMarker(int id);
+ boolean removeCircleMarker(String id);
}
diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/JLAction.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/JLAction.java
new file mode 100644
index 0000000..580f153
--- /dev/null
+++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/JLAction.java
@@ -0,0 +1,81 @@
+package io.github.makbn.jlmap.listener;
+
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import lombok.experimental.FieldDefaults;
+
+/**
+ * @author Matt Akbarian (@makbn)
+ */
+@Getter
+@RequiredArgsConstructor(access = AccessLevel.PRIVATE)
+@FieldDefaults(level = AccessLevel.PRIVATE, makeFinal = true)
+public enum JLAction {
+ MAP_LOADED("load"),
+ MAP_FAILED("failed"),
+ /**
+ * Zoom level changes continuously
+ */
+ ZOOM("zoom"),
+ /**
+ * Zoom level stats to change
+ */
+ ZOOM_START("zoomstart"),
+ /**
+ * Zoom leve changes end
+ */
+ ZOOM_END("zoomend"),
+
+ /**
+ * Element is being moved
+ */
+ MOVE("move"),
+ /**
+ * User starts to move the element
+ */
+ MOVE_START("movestart"),
+ /**
+ * User ends to move the layer
+ */
+ MOVE_END("moveend"),
+
+ /**
+ * The element is being dragged
+ */
+ DRAG("drag"),
+ /**
+ * User starts to drag
+ */
+ DRAG_START("dragstart"),
+ /**
+ * User drag ends
+ */
+ DRAG_END("dragend"),
+ /**
+ * User click on the layer
+ */
+ CLICK("click"),
+ /**
+ * User double-clicks (or double-taps) the layer.
+ */
+ DOUBLE_CLICK("dblclick"),
+ /**
+ * Fired after the layer is added to a map
+ */
+ ADD("add"),
+ /**
+ * Fired after the layer is removed from a map
+ */
+ REMOVE("remove"),
+ /**
+ * Fired when the map is resized.
+ */
+ RESIZE("resize"),
+ /**
+ * Fired when a context menu is requested.
+ */
+ CONTEXT_MENU("contextmenu");
+
+ String jsEventName;
+}
diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/OnJLActionListener.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/OnJLActionListener.java
new file mode 100644
index 0000000..894f32a
--- /dev/null
+++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/OnJLActionListener.java
@@ -0,0 +1,11 @@
+package io.github.makbn.jlmap.listener;
+
+import io.github.makbn.jlmap.listener.event.Event;
+
+/**
+ * @author Matt Akbarian (@makbn)
+ */
+public interface OnJLActionListener
+ * This event is fired when the user clicks or double-clicks a map layer or object. It contains information about
+ * the action (CLICK or DOUBLE_CLICK) and the geographic coordinates where the event occurred.
+ *
+ * Usage in {@link JLInteractionEventHandler}:
+ *
+ * This event allows listeners to react to user interactions, such as showing popups, selecting features, or triggering custom logic.
+ *
+ * This event is fired when a context menu is opened, allowing
+ * listeners to respond to context menu state changes. The event includes
+ * the coordinates where the menu was triggered and the type of action.
+ *
+ * @author Matt Akbarian (@makbn)
+ * @since 2.0.0
+ */
+public record ContextMenuEvent(JLAction action, JLLatLng latLng, JLBounds jlBounds, double x,
+ double y) implements Event {
+
+ public ContextMenuEvent(JLAction action, JLLatLng latLng, JLBounds jlBounds, double... position) {
+ this(action, latLng, jlBounds,
+ position != null && position.length > 0 ? position[0] : 0D,
+ position != null && position.length > 1 ? position[1] : 0D);
+ }
+}
\ No newline at end of file
diff --git a/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/event/DragEvent.java b/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/event/DragEvent.java
new file mode 100644
index 0000000..b4b2ee5
--- /dev/null
+++ b/jlmap-api/src/main/java/io/github/makbn/jlmap/listener/event/DragEvent.java
@@ -0,0 +1,41 @@
+package io.github.makbn.jlmap.listener.event;
+
+import io.github.makbn.jlmap.listener.JLAction;
+import io.github.makbn.jlmap.model.JLBounds;
+import io.github.makbn.jlmap.model.JLLatLng;
+
+/**
+ * Represents a drag event for a map marker or object, analogous to Leaflet's
+ * drag,
+ * dragstart, and
+ * dragend events.
+ *
+ * This event is fired when a marker or object is dragged, starts dragging, or ends dragging.
+ * It contains information about the action (DRAG, DRAG_START, DRAG_END), the new center coordinate,
+ * the map bounds, and the zoom level at the time of the event.
+ *
+ * Usage in {@link JLDragEventHandler}:
+ *
+ * This event allows listeners to react to drag actions, such as updating UI, analytics, or custom logic.
+ *
+ * Subclasses of {@code Event} represent specific types of user or programmatic interactions with the map.
+ * Each event contains a {@link JLAction} describing the type of action performed.
+ *
+ * Known subclasses:
+ *
+ * Implementations of this interface are used in event handlers to provide detailed context about map interactions.
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *