[url_launcher] Documentation improvement for file scheme to readme (#4711)
diff --git a/packages/url_launcher/url_launcher/CHANGELOG.md b/packages/url_launcher/url_launcher/CHANGELOG.md
index 80065cd..5eb5b4a 100644
--- a/packages/url_launcher/url_launcher/CHANGELOG.md
+++ b/packages/url_launcher/url_launcher/CHANGELOG.md
@@ -1,3 +1,9 @@
+## 6.0.19
+
+* Updates README:
+ * Adds description for `file` scheme usage.
+ * Updates `Uri` class link to SDK documentation.
+
## 6.0.18
* Removes dependency on `meta`.
diff --git a/packages/url_launcher/url_launcher/README.md b/packages/url_launcher/url_launcher/README.md
index 393bbd9..a4ffb62 100644
--- a/packages/url_launcher/url_launcher/README.md
+++ b/packages/url_launcher/url_launcher/README.md
@@ -96,16 +96,18 @@
can be formatted using a number of different URL schemes. The supported
URL schemes depend on the underlying platform and installed apps.
-Common schemes supported by both iOS and Android:
+Commonly used schemes include:
-| Scheme | Action |
-|---|---|
-| `http:<URL>` , `https:<URL>`, e.g. `http://flutter.dev` | Open URL in the default browser |
-| `mailto:<email address>?subject=<subject>&body=<body>`, e.g. `mailto:smith@example.org?subject=News&body=New%20plugin` | Create email to <email address> in the default email app |
-| `tel:<phone number>`, e.g. `tel:+1 555 010 999` | Make a phone call to <phone number> using the default phone app |
-| `sms:<phone number>`, e.g. `sms:5550101234` | Send an SMS message to <phone number> using the default messaging app |
+| Scheme | Example | Action |
+|:---|:---|:---|
+| `https:<URL>` | `https://flutter.dev` | Open URL in the default browser |
+| `mailto:<email address>?subject=<subject>&body=<body>` | `mailto:smith@example.org?subject=News&body=New%20plugin` | Create email to <email address> in the default email app |
+| `tel:<phone number>` | `tel:+1-555-010-999` | Make a phone call to <phone number> using the default phone app |
+| `sms:<phone number>` | `sms:5550101234` | Send an SMS message to <phone number> using the default messaging app |
+| `file:<path>` | `file:/home` | Open file or folder using default app association, supported on desktop platforms |
-More details can be found here for [iOS](https://developer.apple.com/library/content/featuredarticles/iPhoneURLScheme_Reference/Introduction/Introduction.html) and [Android](https://developer.android.com/guide/components/intents-common.html)
+More details can be found here for [iOS](https://developer.apple.com/library/content/featuredarticles/iPhoneURLScheme_Reference/Introduction/Introduction.html)
+and [Android](https://developer.android.com/guide/components/intents-common.html)
**Note**: URL schemes are only supported if there are apps installed on the device that can
support them. For example, iOS simulators don't have a default email or phone
@@ -115,7 +117,7 @@
URLs must be properly encoded, especially when including spaces or other special
characters. This can be done using the
-[`Uri` class](https://api.dart.dev/stable/2.7.1/dart-core/Uri-class.html).
+[`Uri` class](https://api.dart.dev/dart-core/Uri-class.html).
For example:
```dart
String? encodeQueryParameters(Map<String, String> params) {
@@ -164,3 +166,25 @@
`enableJavaScript: true`, or else the launch method will not work properly. On
iOS, the default behavior is to open all web URLs within the app. Everything
else is redirected to the app handler.
+
+## File scheme handling
+`file:` scheme can be used on desktop platforms: `macOS`, `Linux` and `Windows`.
+
+We recommend checking first whether the directory or file exists before calling `launch`.
+
+Example:
+```dart
+var filePath = '/path/to/file';
+final Uri uri = Uri.file(filePath);
+
+if (await File(uri.toFilePath()).exists()) {
+ if (!await launch(uri.toString())) {
+ throw 'Could not launch $uri';
+ }
+}
+```
+
+### macOS file access configuration
+
+If you need to access files outside of your application's sandbox, you will need to have the necessary
+[entitlements](https://docs.flutter.dev/desktop#entitlements-and-the-app-sandbox).
diff --git a/packages/url_launcher/url_launcher/pubspec.yaml b/packages/url_launcher/url_launcher/pubspec.yaml
index b0aac36..5d6548a 100644
--- a/packages/url_launcher/url_launcher/pubspec.yaml
+++ b/packages/url_launcher/url_launcher/pubspec.yaml
@@ -3,7 +3,7 @@
web, phone, SMS, and email schemes.
repository: https://github.com/flutter/plugins/tree/main/packages/url_launcher/url_launcher
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+url_launcher%22
-version: 6.0.18
+version: 6.0.19
environment:
sdk: ">=2.14.0 <3.0.0"
