Skip to content

Commit

Permalink
Merge pull request #72 from natsuk4ze/update-document
Browse files Browse the repository at this point in the history
  • Loading branch information
@natsuk4ze
natsuk4ze authored Aug 9, 2023
2 parents 5b6409d + 365c07e commit 0f6c9d3
Show file tree
Hide file tree
Showing 3 changed files with 58 additions and 41 deletions.
74 changes: 40 additions & 34 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@
## ✨Features

* Open gallery
* Save video
* Save image
* Save video (to album)
* Save image (to album)
* Handle permission
* Handle errors
* Lots of docs and wiki
Expand All @@ -42,27 +42,36 @@ $ flutter pub add gal
Add the following key to your _Info.plist_ file, located in
`<project root>/ios/Runner/Info.plist`:

* `<key>NSPhotoLibraryAddUsageDescription</key>` - you can copy from [Info.plist in example](https://github.com/natsuk4ze/gal/blob/main/example/ios/Runner/Info.plist).
* `<key>NSPhotoLibraryAddUsageDescription</key>`
* `<key>NSPhotoLibraryUsageDescription</key>` Requried If you want to save media to album.

you can copy from [Info.plist in example](https://github.com/natsuk4ze/gal/blob/main/example/ios/Runner/Info.plist).

### Android (API <29)

Add the following key to your _AndroidManifest_ file, located in
`<project root>/android/app/src/main/AndroidManifest.xml`:

* `<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
android:maxSdkVersion="29" />` - you can copy from [AndroidManifest.xml in example](https://github.com/natsuk4ze/gal/blob/main/example/android/app/src/main/AndroidManifest.xml).
android:maxSdkVersion="29" />`

you can copy from [AndroidManifest.xml in example](https://github.com/natsuk4ze/gal/blob/main/example/android/app/src/main/AndroidManifest.xml).

## ✅Usage

### Save from local

```dart
//Save Image (Supports two ways)
// Save Image (Supports two ways)
await Gal.putImage('$filePath');
await Gal.putImageBytes('$uint8List');
//Save Video
// Save Video
await Gal.putVideo('$filePath');
// Save to album
await Gal.putImage('$filePath', album: '$album')
...
```

### Download from Internet
Expand All @@ -72,12 +81,12 @@ $ flutter pub add dio
```

```dart
//Download Image
// Download Image
final imagePath = '${Directory.systemTemp.path}/image.jpg';
await Dio().download('$url',imagePath);
await Gal.putImage(imagePath);
//Download Video
// Download Video
final videoPath = '${Directory.systemTemp.path}/video.mp4';
await Dio().download('$url',videoPath);
await Gal.putVideo(videoPath);
Expand All @@ -86,10 +95,10 @@ await Gal.putVideo(videoPath);
### Handle Permission

```dart
//Check Permission
// Check Permission
await Gal.hasAccess();
//Request Access
// Request Permission
await Gal.requestAccess();
```

Expand All @@ -102,9 +111,7 @@ Here is a minimal example. A [best practice](https://github.com/natsuk4ze/gal/wi
import 'package:flutter/material.dart';
import 'package:gal/gal.dart';
void main() {
runApp(const App());
}
void main() => runApp(const App());
class App extends StatelessWidget {
const App({super.key});
Expand All @@ -113,27 +120,26 @@ class App extends StatelessWidget {
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
body: Center(
child: Column(
mainAxisSize: MainAxisSize.min,
children: [
FilledButton.icon(
onPressed: () async => Gal.open(),
label: const Text('Open Gallery'),
icon: const Icon(Icons.open_in_new),
),
FilledButton.icon(
onPressed: () async => Gal.putVideo('TODO: Change this text to video path'),
label: const Text('Save Video'),
icon: const Icon(Icons.video_file),
),
FilledButton.icon(
onPressed: () async => Gal.putImage('TODO: Change this text to image path'),
label: const Text('Save Image'),
icon: const Icon(Icons.image),
),
],
),
body: Column(
children: [
FilledButton.icon(
onPressed: () async => Gal.open(),
label: const Text('Open Gallery'),
icon: const Icon(Icons.open_in_new),
),
FilledButton.icon(
onPressed: () async =>
Gal.putVideo('TODO: Change this text to video path'),
label: const Text('Save Video'),
icon: const Icon(Icons.video_file),
),
FilledButton.icon(
onPressed: () async =>
Gal.putImage('TODO: Change this text to image path'),
label: const Text('Save Image'),
icon: const Icon(Icons.image),
),
],
),
),
);
Expand Down
11 changes: 7 additions & 4 deletions example/ios/Runner/Info.plist
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,15 @@
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<!-- gal -->
<!-- gal: For just saving media -->
<key>NSPhotoLibraryAddUsageDescription</key>
<string>We need add only access to save media files</string>
<string>We need add only access to save medias</string>
<!-- gal: For just saving media -->

<!-- gal: For saving media to album-->
<key>NSPhotoLibraryUsageDescription</key>
<string>We need add only access to save media files</string>
<!-- gal -->
<string>We need access to save medias</string>
<!-- gal: For saving media to album-->

<key>CFBundleDevelopmentRegion</key>
<string>$(DEVELOPMENT_LANGUAGE)</string>
Expand Down
14 changes: 11 additions & 3 deletions lib/src/gal.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ import 'package:gal/src/gal_exception.dart';

import 'gal_platform_interface.dart';

/// A main class of gal.
/// Main class of gal.
///
/// Note: For Android emulators with API < 29 will save media
/// NOTE: For Android emulators with API < 29 will save media
/// on the SD card. Therefore, be sure to set the SD card. You can ignore
/// this for real devices.
/// See: [wiki](https://github.com/natsuk4ze/gal/wiki)
Expand All @@ -16,6 +16,7 @@ final class Gal {

/// Save a video to the gallery from file [path].
///
/// Specify the album with [album]. If it does not exist, it will be created.
/// Throws an [GalException] If you do not have access premission or
/// if an error occurs during saving.
/// See: [Formats](https://github.com/natsuk4ze/gal/wiki/Formats)
Expand All @@ -25,6 +26,7 @@ final class Gal {

/// Save a image to the gallery from file [path].
///
/// Specify the album with [album]. If it does not exist, it will be created.
/// Throws an [GalException] If you do not have access premission or
/// if an error occurs during saving.
/// See: [Formats](https://github.com/natsuk4ze/gal/wiki/Formats)
Expand All @@ -34,7 +36,7 @@ final class Gal {

/// Save a image to the gallery from [Uint8List].
///
/// Save a image directly from memory without using a temporary file.
/// Specify the album with [album]. If it does not exist, it will be created.
/// Throws an [GalException] If you do not have access premission or
/// if an error occurs during saving.
/// See: [Formats](https://github.com/natsuk4ze/gal/wiki/Formats)
Expand All @@ -49,6 +51,9 @@ final class Gal {

/// Check if the app has access permissions.
///
/// On iOS, use the [toAlbum] option, which requires additional permissions
/// to save to an album. on android, it is ignored. If you want to save to
/// an album other than the one created by your app
/// See: [Permissions](https://github.com/natsuk4ze/gal/wiki/Permissions)
static Future<bool> hasAccess({bool toAlbum = false}) async =>
GalPlatform.instance.hasAccess(toAlbum: toAlbum);
Expand All @@ -57,10 +62,13 @@ final class Gal {
///
/// Returns [true] if access is granted, [false] if denied.
/// If access was already granted, the dialog is not displayed and returns true.
/// On iOS, use the [toAlbum] option, which requires additional permissions
/// to save to an album.
/// See: [Permissions](https://github.com/natsuk4ze/gal/wiki/Permissions)
static Future<bool> requestAccess({bool toAlbum = false}) async =>
GalPlatform.instance.requestAccess(toAlbum: toAlbum);

/// Throw [GalException] when [PlatformException] was throwed by native api.
static Future<void> _voidOrThrow(Future<void> Function() cb) async {
try {
return await cb();
Expand Down

0 comments on commit 0f6c9d3

Please sign in to comment.