Offline API ref documentation

toolkit/offline/api/offline.api

@@ -44,20 +44,12 @@ public final class com/arcgismaps/toolkit/offline/OfflineMapAreasKt {
 
 public final class com/arcgismaps/toolkit/offline/OfflineMapInfo {
 	public static final field $stable I
-	public static final field Companion Lcom/arcgismaps/toolkit/offline/OfflineMapInfo$Companion;
 	public synthetic fun <init> (Lcom/arcgismaps/toolkit/offline/OfflineMapInfo$CodableInfo;Landroid/graphics/Bitmap;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public final fun getDescription ()Ljava/lang/String;
 	public final fun getId ()Ljava/lang/String;
 	public final fun getPortalItemUrl ()Ljava/lang/String;
 	public final fun getThumbnail ()Landroid/graphics/Bitmap;
 	public final fun getTitle ()Ljava/lang/String;
-	public final fun saveToDirectory (Ljava/io/File;)V
-}
-
-public final class com/arcgismaps/toolkit/offline/OfflineMapInfo$Companion {
-	public final fun createFromDirectory (Ljava/io/File;)Lcom/arcgismaps/toolkit/offline/OfflineMapInfo;
-	public final fun isSerializedFilePresent (Ljava/io/File;)Z
-	public final fun removeFromDirectory (Ljava/io/File;)V
 }
 
 public final class com/arcgismaps/toolkit/offline/OfflineMapState {
@@ -76,6 +68,6 @@ public final class com/arcgismaps/toolkit/offline/OfflineRepository {
 	public final fun getOfflineMapInfos ()Ljava/util/List;
 	public final fun refreshOfflineMapInfos (Landroid/content/Context;)V
 	public final fun removeAllDownloads (Landroid/content/Context;)V
-	public final fun removeDownloadsForWebmap (Landroid/content/Context;Lcom/arcgismaps/toolkit/offline/OfflineMapInfo;)V
+	public final fun removeDownloads (Landroid/content/Context;Lcom/arcgismaps/toolkit/offline/OfflineMapInfo;)V
 }
 

toolkit/offline/src/main/java/com/arcgismaps/toolkit/offline/OfflineMapAreas.kt

@@ -51,6 +51,60 @@ import com.arcgismaps.toolkit.offline.ui.OfflineMapAreasError
 /**
  * Take a web map offline by downloading map areas.
  *
+ * #### Features
+ *
+ * Supports both ahead-of-time (preplanned) and on-demand map areas for an offline enabled web map. This [OfflineMapAreas] composable:
+ *
+ * - Displays a list of map areas.
+ *
+ * - Shows download progress and status for map areas.
+ *
+ * - Opens a map area for viewing when selected.
+ *
+ * - Provides options to view details about downloaded map areas.
+ *
+ * - Supports removing downloaded offline map areas files from the device.
+ *
+ * For preplanned workflows, this composable:
+ *
+ * - Displays a list of available preplanned map areas from an offline-enabled web map that contains preplanned map areas when the network is connected.
+ *
+ * - Downloads preplanned map areas in the list.
+ *
+ * - Displays a list of downloaded preplanned map areas on the device when the network is disconnected.
+ *
+ * For on-demand workflows, this composable:
+ *
+ * - Allows users to add and download on-demand map areas to the device by specifying an area of interest and level of detail.
+ *
+ * - Displays a list of on-demand map areas available on the device that are tied to a specific web map.
+ *
+ * _Workflow example:_
+ *
+ * ```
+ * val selectedMap = mutableStateOf<ArcGISMap?>(null)
+ *
+ * val displayedMap get() = selectedMap.value ?: onlineMap
+ *
+ * val offlineMapState = OfflineMapState(
+ *     arcGISMap = displayedMap,
+ *     onSelectionChanged = { offlineMap ->
+ *         selectedMap.value = offlineMap
+ *     }
+ * )
+ *
+ * @Composable
+ * fun SheetContent() {
+ *     OfflineMapAreas(
+ *         offlineMapState = offlineMapState,
+ *         modifier = Modifier
+ *             .padding(horizontal = 16.dp)
+ *             .animateContentSize()
+ *     )
+ * }
+ *
+ *```
+ *
  * @since 200.8.0
  */
 @Composable

toolkit/offline/src/main/java/com/arcgismaps/toolkit/offline/OfflineMapInfo.kt

@@ -30,7 +30,12 @@ import java.io.File
 import java.io.FileOutputStream
 
 /**
- * Represents the information of an offline map.
+ * Represents the information for an online map that has been taken offline.
+ *
+ * When a map is taken offline, map information needs to be saved on device so that the map can be reloaded later when the device is offline.
+ * It provides access to and also enables display locally saved map information about downloaded map areas.
+ *
+ * This type is typically used when there is no network connection.
  *
  * @since 200.8.0
  */
@@ -105,14 +110,14 @@ public class OfflineMapInfo private constructor(
         get() = info.portalItemURL
 
 
-    public companion object {
+    internal companion object {
 
         /**
          * Creates an [OfflineMapInfo] from a [directory] on disk, if “info.json” exists.
          *
          * @since 200.8.0
          */
-        public fun createFromDirectory(directory: File): OfflineMapInfo? {
+        internal fun createFromDirectory(directory: File): OfflineMapInfo? {
             val infoFile = File(directory, offlineMapInfoJsonFile)
             if (!infoFile.exists()) {
                 return null
@@ -142,7 +147,7 @@ public class OfflineMapInfo private constructor(
          *
          * @since 200.8.0
          */
-        public fun removeFromDirectory(directory: File) {
+        internal fun removeFromDirectory(directory: File) {
             File(directory, offlineMapInfoJsonFile).delete()
             File(directory, offlineMapInfoThumbnailFile).delete()
         }
@@ -152,7 +157,7 @@ public class OfflineMapInfo private constructor(
          *
          * @since 200.8.0
          */
-        public fun isSerializedFilePresent(directory: File): Boolean {
+        internal fun isSerializedFilePresent(directory: File): Boolean {
             return File(directory, offlineMapInfoJsonFile).exists()
         }
     }
@@ -162,7 +167,7 @@ public class OfflineMapInfo private constructor(
      *
      * @since 200.8.0
      */
-    public fun saveToDirectory(directory: File) {
+    internal fun saveToDirectory(directory: File) {
         if (!directory.exists()) {
             directory.mkdirs()
         }

toolkit/offline/src/main/java/com/arcgismaps/toolkit/offline/OfflineMapState.kt

@@ -45,18 +45,64 @@ import java.io.File
 import java.io.IOException
 
 /**
- * Represents the state of the offline map.
+ * Represents the state of the [OfflineMapAreas] composable.
+ *
+ * #### Behavior
+ *
+ * This state class provides two constructors to initialize the [OfflineMapAreas] composable using an [ArcGISMap] or an [OfflineMapInfo].
+ * Therefore, the [OfflineMapAreas] composable can be used either when the device is connected to or disconnected from the network.
+ *
+ * In other words, the composable can be used in the following situations:
+ *
+ * - When the device is connected to the network…
+ *     - Displays preplanned map areas from a web map that are available for download.
+ *     - When the web map doesn’t contain preplanned map areas, users can add and download on-demand map areas by specifying a geographic area and level of detail.
+ *     - Use the constructor with [ArcGISMap] to create the state.
+ *
+ * - When the device is disconnected from the network…
+ *     - Displays only downloaded map areas by retrieving offline map info from the device.
+ *     - Use the constructor with [OfflineMapInfo] to create the state.
+ *
+ * - When the device network connection has changed…
+ *     - Re-initialize the the state `OfflineMapState` using the desired constructor.
+ *
+ * #### Associated Types
+ *
+ * `OfflineMapState` has the following associated types:
+ *
+ * - [OfflineMapAreas]
+ * - [OfflineRepository]
+ * - [OfflineMapInfo]
  *
  * @since 200.8.0
  */
 @Stable
-public class OfflineMapState(
-    private val arcGISMap: ArcGISMap,
-    private val onSelectionChanged: (ArcGISMap?) -> Unit = { }
-) {
+public class OfflineMapState {
+    private val arcGISMap: ArcGISMap
+    private val onSelectionChanged: ((ArcGISMap?) -> Unit)
+
+    /**
+     * Represents the state of the offline map with a given [ArcGISMap].
+     *
+     * @param arcGISMap The web map to be taken offline.
+     * @param onSelectionChanged A callback for the currently selected offline map.
+     *
+     * @since 200.8.0
+     */
+    public constructor(
+        arcGISMap: ArcGISMap,
+        onSelectionChanged: (ArcGISMap?) -> Unit = { }
+    ) {
+        this.arcGISMap = arcGISMap
+        this.onSelectionChanged = onSelectionChanged
+    }
+
     /**
      * Represents the state of the offline map with a given [OfflineMapInfo].
      *
+     * @param offlineMapInfo The offline map info for which to create the state.
+     * @param onSelectionChanged A callback for the currently selected offline map.
+     *
      * @since 200.8.0
      */
     public constructor(
@@ -388,7 +434,7 @@ public class OfflineMapState(
     }
 
     /**
-     * Resets the current selection of preplanned map areas.
+     * Resets the current selection of the map areas.
      *
      * @since 200.8.0
      */

toolkit/offline/src/main/java/com/arcgismaps/toolkit/offline/OfflineRepository.kt

@@ -98,7 +98,7 @@ public object OfflineRepository {
      * @param offlineMapInfo The [OfflineMapInfo] to remove.
      * @since 200.8.0
      */
-    public fun removeDownloadsForWebmap(context: Context, offlineMapInfo: OfflineMapInfo) {
+    public fun removeDownloads(context: Context, offlineMapInfo: OfflineMapInfo) {
         _offlineMapInfos.remove(offlineMapInfo)
         val baseDir = File(OfflineURLs.offlineRepositoryDirectoryPath(context))
         val offlineMapInfoDir = File(baseDir, offlineMapInfo.id)
@@ -147,6 +147,7 @@ public object OfflineRepository {
             mapAreaMetadata.saveToDirectory(pendingAreaMetadataDir)
         }
     }
+
     /**
      * Returns preplanned/on-demand map area [OfflineMapAreaMetadata] using the corresponding job [UUID].
      *