Skip to content

Commit 8b7dd6f

Browse files
afarberafarber
committed
Unclutter the root README.md
1 parent a974a39 commit 8b7dd6f

File tree

2 files changed

+260
-33
lines changed

2 files changed

+260
-33
lines changed

‎README.md‎

Lines changed: 8 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -39,39 +39,14 @@ The documentation is automatically generated from KDoc comments and updated with
3939

4040
Explore the example applications to see OpenMapView in action:
4141

42-
### [Example01Pan](examples/Example01Pan) - Basic Map Panning
43-
44-
![Example01Pan](examples/Example01Pan/screenshot.gif)
45-
46-
Demonstrates basic map tile rendering and touch pan gestures.
47-
48-
### [Example02Zoom](examples/Example02Zoom) - Zoom Controls and Gestures
49-
50-
![Example02Zoom](examples/Example02Zoom/screenshot.gif)
51-
52-
Shows zoom functionality with FAB controls and pinch-to-zoom gestures.
53-
54-
### [Example03Markers](examples/Example03Markers) - Marker Overlays
55-
56-
![Example03Markers](examples/Example03Markers/screenshot.gif)
57-
58-
Demonstrates marker system with custom icons and click handling.
59-
60-
### [Example04Polylines](examples/Example04Polylines) - Polylines and Polygons
61-
62-
![Example04Polylines](examples/Example04Polylines/screenshot.gif)
63-
64-
Shows how to draw vector shapes including polylines, filled polygons, and polygons with holes.
65-
66-
### [Example05Camera](examples/Example05Camera) - Camera Animations
67-
68-
![Example05Camera](examples/Example05Camera/screenshot.gif)
69-
70-
Demonstrates smooth camera animations with customizable durations and completion callbacks.
71-
72-
### [Example06Clicks](examples/Example06Clicks) - Map Click Listeners
73-
74-
Demonstrates map click and long-click listeners with coordinate display via Toast messages.
42+
- [Example01Pan](examples/Example01Pan) - Basic map panning with touch gestures
43+
- [Example02Zoom](examples/Example02Zoom) - Zoom controls and pinch-to-zoom
44+
- [Example03Markers](examples/Example03Markers) - Marker overlays with custom icons
45+
- [Example04Polylines](examples/Example04Polylines) - Polylines, polygons, and polygons with holes
46+
- [Example05Camera](examples/Example05Camera) - Camera animations with callbacks
47+
- [Example06Clicks](examples/Example06Clicks) - Map click and long-click listeners
48+
49+
![Example05Camera Demo](examples/Example05Camera/screenshot.gif)
7550

7651
## Documentation
7752

‎examples/Example06Clicks/README.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
# Example06Clicks - Map Click Listeners
2+
3+
This example demonstrates map click and long-click event handling in OpenMapView, showing how to detect user taps on the map and convert screen coordinates to geographic coordinates.
4+
5+
## Features Demonstrated
6+
7+
- Map click listener (single tap)
8+
- Map long-click listener (tap and hold)
9+
- Screen coordinate to LatLng conversion
10+
- Real-time coordinate display via Toast messages
11+
- Lifecycle-safe event handling
12+
13+
## Screenshot
14+
15+
![Example06Clicks Demo](screenshot.gif)
16+
17+
## Quick Start
18+
19+
### Option 1: Run in Android Studio
20+
21+
1. Open the OpenMapView project in Android Studio
22+
2. Select `examples.Example06Clicks` from the run configuration dropdown
23+
3. Click Run (green play button)
24+
4. Deploy to device or emulator
25+
26+
### Option 2: Build and Install from Command Line
27+
28+
```bash
29+
# From project root - build, install, and launch
30+
./gradlew :examples:Example06Clicks:installDebug
31+
32+
# Launch the app
33+
adb shell am start -n de.afarber.openmapview.example06clicks/.MainActivity
34+
```
35+
36+
## Code Highlights
37+
38+
### Setting Up Click Listeners
39+
40+
```kotlin
41+
// Single tap listener
42+
mapView.setOnMapClickListener { latLng ->
43+
Toast.makeText(
44+
this,
45+
"Clicked: ${latLng.latitude}, ${latLng.longitude}",
46+
Toast.LENGTH_SHORT
47+
).show()
48+
}
49+
50+
// Long-press listener
51+
mapView.setOnMapLongClickListener { latLng ->
52+
Toast.makeText(
53+
this,
54+
"Long-clicked: ${latLng.latitude}, ${latLng.longitude}",
55+
Toast.LENGTH_LONG
56+
).show()
57+
}
58+
```
59+
60+
### Coordinate Conversion
61+
62+
```kotlin
63+
// Convert screen pixels to geographic coordinates
64+
val latLng = mapView.screenToLatLng(screenX, screenY)
65+
```
66+
67+
## Key Concepts
68+
69+
### OnMapClickListener
70+
71+
Functional interface for single tap events:
72+
73+
```kotlin
74+
fun interface OnMapClickListener {
75+
fun onMapClick(latLng: LatLng)
76+
}
77+
```
78+
79+
- Triggered on single tap
80+
- Receives LatLng of tapped location
81+
- Does not interfere with pan gestures
82+
83+
### OnMapLongClickListener
84+
85+
Functional interface for long-press events:
86+
87+
```kotlin
88+
fun interface OnMapLongClickListener {
89+
fun onMapLongClick(latLng: LatLng)
90+
}
91+
```
92+
93+
- Triggered after ~500ms press
94+
- Receives LatLng of pressed location
95+
- Uses Android GestureDetector for reliable detection
96+
97+
### Screen to Geographic Conversion
98+
99+
The library automatically converts screen coordinates to geographic coordinates using Web Mercator projection:
100+
101+
```kotlin
102+
// Internal implementation in MapController
103+
fun screenToLatLng(screenX: Float, screenY: Float): LatLng {
104+
val worldX = (screenX - (viewportWidth / 2f)) / scale + centerWorldX
105+
val worldY = (screenY - (viewportHeight / 2f)) / scale + centerWorldY
106+
107+
return LatLng(
108+
latitude = worldYToLat(worldY),
109+
longitude = worldXToLon(worldX)
110+
)
111+
}
112+
```
113+
114+
## What to Test
115+
116+
1. Single Tap - Tap anywhere on the map to see coordinates in a short toast
117+
2. Long Press - Press and hold to see coordinates in a longer toast
118+
3. Zoom Interaction - Clicks work at any zoom level
119+
4. Pan Interaction - Panning does not trigger click events
120+
5. Toast Messages - Coordinates are displayed with full precision
121+
6. Lifecycle - Listeners are cleaned up on activity destroy
122+
123+
## Touch Event Priority
124+
125+
OpenMapView handles touch events in this order:
126+
127+
1. Scale gestures (pinch-to-zoom)
128+
2. Long-press detection
129+
3. Single tap detection
130+
4. Pan gestures
131+
132+
This ensures zoom and long-press have priority over panning.
133+
134+
## Technical Details
135+
136+
### GestureDetector Integration
137+
138+
The library uses Android's GestureDetector for reliable touch event handling:
139+
140+
- `onSingleTapConfirmed()` - Fires click listener after confirming single tap
141+
- `onLongPress()` - Fires long-click listener after 500ms press
142+
- Automatically distinguishes between tap, long-press, and pan gestures
143+
144+
### Coordinate Precision
145+
146+
LatLng coordinates are returned as Double values with full precision:
147+
148+
```kotlin
149+
LatLng(
150+
latitude = 51.466123456789,
151+
longitude = 7.249087654321
152+
)
153+
```
154+
155+
This precision is suitable for:
156+
- Adding markers at tapped locations
157+
- Measuring distances between points
158+
- Geocoding and reverse geocoding
159+
- Route planning
160+
161+
### Performance
162+
163+
- Touch event processing is highly optimized
164+
- Coordinate conversion uses efficient Web Mercator formulas
165+
- No performance impact on map rendering
166+
- Listeners are called on the UI thread
167+
168+
## Advanced Usage
169+
170+
### Adding Markers on Tap
171+
172+
```kotlin
173+
mapView.setOnMapClickListener { latLng ->
174+
mapView.addMarker(Marker(
175+
position = latLng,
176+
title = "Tapped Location"
177+
))
178+
}
179+
```
180+
181+
### Measuring Distance Between Points
182+
183+
```kotlin
184+
var firstPoint: LatLng? = null
185+
186+
mapView.setOnMapClickListener { latLng ->
187+
val first = firstPoint
188+
if (first == null) {
189+
firstPoint = latLng
190+
Toast.makeText(this, "Tap second point", Toast.LENGTH_SHORT).show()
191+
} else {
192+
val distance = calculateDistance(first, latLng)
193+
Toast.makeText(
194+
this,
195+
"Distance: ${distance}m",
196+
Toast.LENGTH_LONG
197+
).show()
198+
firstPoint = null
199+
}
200+
}
201+
```
202+
203+
### Context Menu on Long Press
204+
205+
```kotlin
206+
mapView.setOnMapLongClickListener { latLng ->
207+
AlertDialog.Builder(this)
208+
.setTitle("Map Actions")
209+
.setItems(arrayOf("Add Marker", "Share Location", "Navigate")) { _, which ->
210+
when (which) {
211+
0 -> addMarkerAt(latLng)
212+
1 -> shareLocation(latLng)
213+
2 -> startNavigation(latLng)
214+
}
215+
}
216+
.show()
217+
}
218+
```
219+
220+
### Combining with Marker Click Listeners
221+
222+
```kotlin
223+
// Map click listener
224+
mapView.setOnMapClickListener { latLng ->
225+
Toast.makeText(this, "Map clicked", Toast.LENGTH_SHORT).show()
226+
}
227+
228+
// Marker click listener
229+
mapView.setOnMarkerClickListener { marker ->
230+
Toast.makeText(this, "Marker: ${marker.title}", Toast.LENGTH_SHORT).show()
231+
true // Return true to consume the event
232+
}
233+
```
234+
235+
When a marker is clicked:
236+
- If marker listener returns `true`, event is consumed (map click not fired)
237+
- If marker listener returns `false`, event propagates to map click listener
238+
239+
## Next Steps
240+
241+
- Try [Example01Pan](../Example01Pan) for basic map panning
242+
- Try [Example02Zoom](../Example02Zoom) for zoom controls
243+
- Try [Example03Markers](../Example03Markers) for marker overlays
244+
- Try [Example04Polylines](../Example04Polylines) for vector shapes
245+
- Try [Example05Camera](../Example05Camera) for camera animations
246+
- Experiment with adding markers on tap
247+
- Build a distance measurement tool
248+
- Create custom context menus on long-press
249+
250+
## Map Location
251+
252+
Default Center: Bochum, Germany (51.4620°N, 7.2480°E) at zoom 13.0

0 commit comments

Comments
 (0)