From 527e24ef6b7fec1767090727d6871f7d85c4a991 Mon Sep 17 00:00:00 2001 From: savsch Date: Thu, 26 Dec 2024 18:23:43 +0530 Subject: [PATCH] Nearby offline pins: Add javadoc --- .../java/fr/free/nrw/commons/nearby/PlaceDao.java | 9 +++++++++ .../nrw/commons/nearby/PlacesLocalDataSource.java | 8 ++++++++ .../free/nrw/commons/nearby/PlacesRepository.java | 7 +++++++ .../nearby/fragments/NearbyParentFragment.java | 15 +++++++++++++++ .../presenter/NearbyParentFragmentPresenter.kt | 6 ++++++ 5 files changed, 45 insertions(+) diff --git a/app/src/main/java/fr/free/nrw/commons/nearby/PlaceDao.java b/app/src/main/java/fr/free/nrw/commons/nearby/PlaceDao.java index 7d40d2543..269384ffa 100644 --- a/app/src/main/java/fr/free/nrw/commons/nearby/PlaceDao.java +++ b/app/src/main/java/fr/free/nrw/commons/nearby/PlaceDao.java @@ -33,6 +33,15 @@ public abstract class PlaceDao { @Query("SELECT * from place WHERE entityID=:entity") public abstract Place getPlace(String entity); + /** + * Retrieves a list of places within the specified rectangular area. + * + * @param latBegin Latitudinal lower bound + * @param lngBegin Longitudinal lower bound + * @param latEnd Latitudinal upper bound, should be greater than `latBegin` + * @param lngEnd Longitudinal upper bound, should be greater than `lngBegin` + * @return The list of places within the specified rectangular geographical area. + */ @Query("SELECT * from place WHERE name!='' AND latitude>=:latBegin AND longitude>=:lngBegin " + "AND latitude<:latEnd AND longitude<:lngEnd") public abstract List fetchPlaces(double latBegin, double lngBegin, diff --git a/app/src/main/java/fr/free/nrw/commons/nearby/PlacesLocalDataSource.java b/app/src/main/java/fr/free/nrw/commons/nearby/PlacesLocalDataSource.java index 4a4e359f5..2d8c2733a 100644 --- a/app/src/main/java/fr/free/nrw/commons/nearby/PlacesLocalDataSource.java +++ b/app/src/main/java/fr/free/nrw/commons/nearby/PlacesLocalDataSource.java @@ -30,6 +30,14 @@ public class PlacesLocalDataSource { return placeDao.getPlace(entityID); } + /** + * Retrieves a list of places from the database within the geographical area + * specified by map's opposite corners. + * + * @param mapBottomLeft Bottom left corner of the map. + * @param mapTopRight Top right corner of the map. + * @return The list of saved places within the map's view. + */ public List fetchPlaces(final LatLng mapBottomLeft, final LatLng mapTopRight) { class Constraint { diff --git a/app/src/main/java/fr/free/nrw/commons/nearby/PlacesRepository.java b/app/src/main/java/fr/free/nrw/commons/nearby/PlacesRepository.java index 21b3663f6..c2edfe355 100644 --- a/app/src/main/java/fr/free/nrw/commons/nearby/PlacesRepository.java +++ b/app/src/main/java/fr/free/nrw/commons/nearby/PlacesRepository.java @@ -40,6 +40,13 @@ public class PlacesRepository { return localDataSource.fetchPlace(entityID); } + /** + * Retrieves a list of places within the geographical area specified by map's opposite corners. + * + * @param mapBottomLeft Bottom left corner of the map. + * @param mapTopRight Top right corner of the map. + * @return The list of saved places within the map's view. + */ public List fetchPlaces(final LatLng mapBottomLeft, final LatLng mapTopRight) { return localDataSource.fetchPlaces(mapBottomLeft, mapTopRight); } diff --git a/app/src/main/java/fr/free/nrw/commons/nearby/fragments/NearbyParentFragment.java b/app/src/main/java/fr/free/nrw/commons/nearby/fragments/NearbyParentFragment.java index 768cbcd8d..de92ca09a 100644 --- a/app/src/main/java/fr/free/nrw/commons/nearby/fragments/NearbyParentFragment.java +++ b/app/src/main/java/fr/free/nrw/commons/nearby/fragments/NearbyParentFragment.java @@ -1039,6 +1039,11 @@ public class NearbyParentFragment extends CommonsDaggerSupportFragment }; } + /** + * Updates the internet unavailable snackbar to reflect whether cached pins are shown. + * + * @param offlinePinsShown Whether there are pins currently being shown on map. + */ @Override public void updateSnackbar(final boolean offlinePinsShown) { if (!isNetworkErrorOccurred || snackbar == null) { @@ -1065,6 +1070,11 @@ public class NearbyParentFragment extends CommonsDaggerSupportFragment } } + /** + * Returns the location of the top right corner of the map view. + * + * @return a `LatLng` object denoting the location of the top right corner of the map. + */ @Override public LatLng getScreenTopRight() { final IGeoPoint screenTopRight = binding.map.getProjection() @@ -1073,6 +1083,11 @@ public class NearbyParentFragment extends CommonsDaggerSupportFragment screenTopRight.getLatitude(), screenTopRight.getLongitude(), 0); } + /** + * Returns the location of the bottom left corner of the map view. + * + * @return a `LatLng` object denoting the location of the bottom left corner of the map. + */ @Override public LatLng getScreenBottomLeft() { final IGeoPoint screenBottomLeft = binding.map.getProjection() diff --git a/app/src/main/java/fr/free/nrw/commons/nearby/presenter/NearbyParentFragmentPresenter.kt b/app/src/main/java/fr/free/nrw/commons/nearby/presenter/NearbyParentFragmentPresenter.kt index c8c456795..2ddf05ae9 100644 --- a/app/src/main/java/fr/free/nrw/commons/nearby/presenter/NearbyParentFragmentPresenter.kt +++ b/app/src/main/java/fr/free/nrw/commons/nearby/presenter/NearbyParentFragmentPresenter.kt @@ -492,6 +492,12 @@ class NearbyParentFragmentPresenter } } + /** + * Handles the map scroll user action for `NearbyParentFragment` + * + * @param scope The lifecycle scope of `nearbyParentFragment`'s `viewLifecycleOwner` + * @param isNetworkAvailable Whether to load pins from the internet or from the cache. + */ @Override override fun handleMapScrolled(scope: LifecycleCoroutineScope?, isNetworkAvailable: Boolean) { scope ?: return