Skip to content

Commit

Permalink
Merge pull request #68 from MohamedRejeb/0.3.1
Browse files Browse the repository at this point in the history
Update calf-file-picker Docs
  • Loading branch information
MohamedRejeb authored Mar 4, 2024
2 parents cec6805 + 9fcd586 commit 3ee169a
Show file tree
Hide file tree
Showing 11 changed files with 183 additions and 56 deletions.
62 changes: 40 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,32 +15,39 @@ Calf stands for **C**ompose **A**daptive **L**ook & **F**eel

## Artifacts

| Artifact | Description | Platforms | Version |
|-----------------------|-------------------------------------------|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **calf-ui** | Adaptive UI components | Android, iOS, Desktop, Web | [![Maven Central](https://img.shields.io/maven-central/v/com.mohamedrejeb.calf/calf-ui)](https://search.maven.org/search?q=g:%22com.mohamedrejeb.calf%22%20AND%20a:%calf-ui%22) |
| **calf-file-picker** | Native File Picker wrapper | Android, iOS, Desktop, Web | [![Maven Central](https://img.shields.io/maven-central/v/com.mohamedrejeb.calf/calf-file-picker)](https://search.maven.org/search?q=g:%22com.mohamedrejeb.calf%22%20AND%20a:%calf-file-picker%22) |
| **calf-permissions** | API that allows you to handle permissions | Android, iOS | [![Maven Central](https://img.shields.io/maven-central/v/com.mohamedrejeb.calf/calf-file-picker)](https://search.maven.org/search?q=g:%22com.mohamedrejeb.calf%22%20AND%20a:%calf-file-picker%22) |
| **calf-geo** | API that allows you to access geolocation | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-navigation** | Native navigation wrapper | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-map** | Native Maps wrapper | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-media** | Video/Audio player | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-notification** | Notification manager | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-sf-symbols** | Apple SF Symbols icons | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| Artifact | Description | Platforms | Version |
|-----------------------|-------------------------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **calf-ui** | Adaptive UI components | Android, iOS, Desktop, Web(Js, Wasm) | [![Maven Central](https://img.shields.io/maven-central/v/com.mohamedrejeb.calf/calf-ui)](https://search.maven.org/search?q=g:%22com.mohamedrejeb.calf%22%20AND%20a:%calf-ui%22) |
| **calf-file-picker** | Native File Picker wrapper | Android, iOS, Desktop, Web(Js, Wasm) | [![Maven Central](https://img.shields.io/maven-central/v/com.mohamedrejeb.calf/calf-file-picker)](https://search.maven.org/search?q=g:%22com.mohamedrejeb.calf%22%20AND%20a:%calf-file-picker%22) |
| **calf-permissions** | API that allows you to handle permissions | Android, iOS | [![Maven Central](https://img.shields.io/maven-central/v/com.mohamedrejeb.calf/calf-file-picker)](https://search.maven.org/search?q=g:%22com.mohamedrejeb.calf%22%20AND%20a:%calf-file-picker%22) |
| **calf-geo** | API that allows you to access geolocation | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-navigation** | Native navigation wrapper | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-map** | Native Maps wrapper | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-media** | Video/Audio player | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-notification** | Notification manager | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |
| **calf-sf-symbols** | Apple SF Symbols icons | Coming soon... 🚧 🚧 | Coming soon... 🚧 🚧 |

> The main focus for now is Android and iOS, but more Desktop components are coming that allows you to create adaptive UIs for Desktop as well (Windows, macOS, Linux)
## Installation

[![Maven Central](https://img.shields.io/maven-central/v/com.mohamedrejeb.calf/calf-ui)](https://search.maven.org/search?q=g:%22com.mohamedrejeb.calf%22%20AND%20a:%calf-ui%22)

| Kotlin version | Compose version | Calf version |
|----------------|-----------------|--------------|
| 1.9.22 | 1.6.0 | 0.4.0 |
| 1.9.21 | 1.5.11 | 0.3.1 |
| 1.9.20 | 1.5.10 | 0.2.0 |
| 1.9.0 | 1.5.0 | 0.1.1 |

Add the following dependency to your module `build.gradle.kts` file:

```kotlin
// For Adaptive UI components
api("com.mohamedrejeb.calf:calf-ui:0.3.1")
api("com.mohamedrejeb.calf:calf-ui:0.4.0")

// For Adaptive FilePicker
implementation("com.mohamedrejeb.calf:calf-file-picker:0.3.1")
implementation("com.mohamedrejeb.calf:calf-file-picker:0.4.0")
```

If you are using `calf-ui` artifact, make sure to export it to binaries:
Expand All @@ -56,7 +63,7 @@ kotlin {
.forEach {
it.binaries.framework {
...
export("com.mohamedrejeb.calf:calf-ui:0.3.1")
export("com.mohamedrejeb.calf:calf-ui:0.4.0")
}
}
...
Expand All @@ -73,7 +80,7 @@ kotlin {
...
framework {
...
export("com.mohamedrejeb.calf:calf-ui:0.3.1")
export("com.mohamedrejeb.calf:calf-ui:0.4.0")
}
}
...
Expand Down Expand Up @@ -286,19 +293,28 @@ LaunchedEffect(Unit) {

Calf File Picker allows you to pick files from the device storage.

| Android | iOS |
|------------------------------------------------------------|----------------------------------------------------|
| ![Web View Android](docs/images/AdaptiveFilePicker-android.png) | ![Web View iOS](docs/images/AdaptiveFilePicker-ios.png) |
| Android | iOS |
|--------------------------------------------------------------------|------------------------------------------------------------|
| ![File Picker Android](docs/images/AdaptiveFilePicker-android.png) | ![File Picker iOS](docs/images/AdaptiveFilePicker-ios.png) |

| Desktop | Web |
|--------------------------------------------------------------------|------------------------------------------------------------|
| ![File Picker Desktop](docs/images/AdaptiveFilePicker-desktop.png) | ![File Picker Web](docs/images/AdaptiveFilePicker-web.png) |

```kotlin
val scope = rememberCoroutineScope()
val context = LocalPlatformContext.current

val pickerLauncher = rememberFilePickerLauncher(
type = FilePickerFileType.Image,
selectionMode = FilePickerSelectionMode.Single,
onResult = { files ->
files.firstOrNull()?.let { file ->
// Do something with the selected file
// You can get the ByteArray of the file
file.readByteArray()
scope.launch {
files.firstOrNull()?.let { file ->
// Do something with the selected file
// You can get the ByteArray of the file
file.readByteArray(context)
}
}
}
)
Expand Down Expand Up @@ -345,6 +361,8 @@ val type = FilePickerFileType.Custom(
* `FilePickerSelectionMode.Single` - Allows you to pick a single file
* `FilePickerSelectionMode.Multiple` - Allows you to pick multiple files

Read the full file picker documentation [here](docs/filepicker.md).

## Contribution
If you've found an error in this sample, please file an issue. <br>
Feel free to help out by sending a pull request :heart:.
Expand Down
109 changes: 100 additions & 9 deletions docs/filepicker.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,26 +7,36 @@
Add the following dependency to your module `build.gradle.kts` file:

```kotlin
implementation("com.mohamedrejeb.calf:calf-file-picker:0.3.1")
implementation("com.mohamedrejeb.calf:calf-file-picker:0.4.0")
```

## Usage

Calf File Picker allows you to pick files from the device storage.

| Android | iOS |
|------------------------------------------------------------|----------------------------------------------------|
| ![Web View Android](images/AdaptiveFilePicker-android.png) | ![Web View iOS](images/AdaptiveFilePicker-ios.png) |

| Android | iOS |
|---------------------------------------------------------------|-------------------------------------------------------|
| ![File Picker Android](images/AdaptiveFilePicker-android.png) | ![File Picker iOS](images/AdaptiveFilePicker-ios.png) |

| Desktop | Web |
|---------------------------------------------------------------|-------------------------------------------------------|
| ![File Picker Desktop](images/AdaptiveFilePicker-desktop.png) | ![File Picker Web](images/AdaptiveFilePicker-web.png) |

```kotlin
val scope = rememberCoroutineScope()
val context = LocalPlatformContext.current

val pickerLauncher = rememberFilePickerLauncher(
type = FilePickerFileType.Image,
selectionMode = FilePickerSelectionMode.Single,
onResult = { files ->
files.firstOrNull()?.let { file ->
// Do something with the selected file
// You can get the ByteArray of the file
file.readByteArray()
scope.launch {
files.firstOrNull()?.let { file ->
// Do something with the selected file
// You can get the ByteArray of the file
file.readByteArray(context)
}
}
}
)
Expand Down Expand Up @@ -71,4 +81,85 @@ val type = FilePickerFileType.Custom(
`FilePickerSelectionMode` allows you to specify the selection mode of the file picker:

* `FilePickerSelectionMode.Single` - Allows you to pick a single file
* `FilePickerSelectionMode.Multiple` - Allows you to pick multiple files
* `FilePickerSelectionMode.Multiple` - Allows you to pick multiple files

#### Extensions

* Read the `ByteArray` of the file using the `readByteArray` extension function:

```kotlin
val context = LocalPlatformContext.current

LaunchedEffect(file) {
val byteArray = file.readByteArray(context)
}
```

> The `readByteArray` extension function is a suspending function, so you need to call it from a coroutine scope.
> It's not recommended to use `readByteArray` extension function on large files, as it reads the entire file into memory.
> For large files, it's recommended to use the platform-specific APIs to read the file.
* Check if the file exists using the `exists` extension function:

```kotlin
val context = LocalPlatformContext.current

val exists = file.exists(context)
```

* Get the file name using the `getName` extension function:

```kotlin
val context = LocalPlatformContext.current

val name = file.getName(context)
```

* Get the file path using the `getPath` extension function:

```kotlin
val context = LocalPlatformContext.current

val path = file.getPath(context)
```

* Check if the file is a directory using the `isDirectory` extension function:

```kotlin
val context = LocalPlatformContext.current

val isDirectory = file.isDirectory(context)
```

* Check if the file is a file using the `isFile` extension function:

```kotlin
val context = LocalPlatformContext.current

val isFile = file.isFile(context)
```

#### Platform-specific APIs

KmpFile is a wrapper around platform-specific APIs, so you can use the platform-specific APIs to read the file:

##### Android
```kotlin
val uri: Uri = kmpFile.uri
```

##### iOS
```kotlin
val nsUrl: NSURL = kmpFile.nsUrl
```

##### Desktop
```kotlin
val file: java.io.File = kmpFile.file
```

##### Web
```kotlin
val file: org.w3c.files.File = kmpFile.file
```
Binary file added docs/images/AdaptiveFilePicker-desktop.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/AdaptiveFilePicker-web.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 3ee169a

Please sign in to comment.