Updates docs and removes deprecated call warnings

CHANGELOG.md

@@ -1,3 +1,18 @@
+## 3.0.2
+##### General
+- `name` and `size` properties are now non-nullable types.
+##### Docs
+- Updates README;
+- Updates API docs;
+
+##### Example
+- Updates Android example app to V2;
+##### Android
+- Removes deprecated call warnings;
+
+##### Other
+- Adds analysis_options.yaml with linter rule to surpress warnings from generated_plugin_registrant.
+
 ## 3.0.1
 #### Android
 - Use MediaStore Opener (which goes through the gallery) instead of default explorer. (Thank you @tmthecoder).

README.md

@@ -53,7 +53,7 @@ Quick simple usage example:
 
 #### Single file
 ```
-FilePickerResult result = await FilePicker.platform.pickFiles();
+FilePickerResult? result = await FilePicker.platform.pickFiles();
 
 if(result != null) {
    File file = File(result.files.single.path);
@@ -63,7 +63,7 @@ if(result != null) {
 ```
 #### Multiple files
 ```
-FilePickerResult result = await FilePicker.platform.pickFiles(allowMultiple: true);
+FilePickerResult? result = await FilePicker.platform.pickFiles(allowMultiple: true);
 
 if(result != null) {
    List<File> files = result.paths.map((path) => File(path)).toList();
@@ -73,14 +73,14 @@ if(result != null) {
 ```
 #### Multiple files with extension filter
 ```
-FilePickerResult result = await FilePicker.platform.pickFiles(
+FilePickerResult? result = await FilePicker.platform.pickFiles(
           type: FileType.custom,
           allowedExtensions: ['jpg', 'pdf', 'doc'],
         );
 ```
 ### Load result and file details
 ```
-FilePickerResult result = await FilePicker.platform.pickFiles();
+FilePickerResult? result = await FilePicker.platform.pickFiles();
 
 if(result != null) {
    PlatformFile file = result.files.first;
@@ -94,6 +94,18 @@ if(result != null) {
    // User canceled the picker
 }
 ```
+#### Pick and upload a file to Firebase Storage with Flutter Web
+```
+FilePickerResult? result = await FilePicker.platform.pickFiles();
+
+if (result != null) {
+  Uint8List fileBytes = result.files.first.bytes;
+  String fileName = result.files.first.name;
+  
+  // Upload file
+  await FirebaseStorage.instance.ref('uploads/$fileName').putData(fileBytes);
+}
+```
 
 For full usage details refer to the **[Wiki](https://github.com/miguelpruivo/flutter_file_picker/wiki)** above.
 

analysis_options.yaml

@@ -0,0 +1,3 @@
+analyzer:
+  exclude:
+    - lib/generated_plugin_registrant.dart

android/src/main/java/com/mr/flutter/plugin/filepicker/FilePickerPlugin.java

@@ -23,11 +23,11 @@ import io.flutter.plugin.common.EventChannel;
 import io.flutter.plugin.common.MethodCall;
 import io.flutter.plugin.common.MethodChannel;
 import io.flutter.plugin.common.PluginRegistry;
-import io.flutter.plugin.common.PluginRegistry.Registrar;
 
 /**
  * FilePickerPlugin
  */
+@SuppressWarnings("deprecation")
 public class FilePickerPlugin implements MethodChannel.MethodCallHandler, FlutterPlugin, ActivityAware {
 
     private static final String TAG = "FilePicker";
@@ -117,7 +117,7 @@ public class FilePickerPlugin implements MethodChannel.MethodCallHandler, Flutte
     /**
      * Plugin registration.
      */
-    public static void registerWith(final Registrar registrar) {
+    public static void registerWith(final io.flutter.plugin.common.PluginRegistry.Registrar registrar) {
 
         if (registrar.activity() == null) {
             // If a background flutter view tries to register the plugin, there will be no activity from the registrar,

example/android/app/src/main/AndroidManifest.xml

@@ -14,7 +14,6 @@
          additional functionality it is fine to subclass or reimplement
          FlutterApplication and put your custom class here. -->
     <application
-        android:name="io.flutter.app.FlutterApplication"
         android:label="file_picker_example"
         android:icon="@mipmap/ic_launcher"
         tools:replace="android:label"
@@ -33,6 +32,9 @@
             <meta-data
                 android:name="io.flutter.app.android.SplashScreenUntilFirstFrame"
                 android:value="true" />
+            <meta-data
+                android:name="flutterEmbedding"
+                android:value="2" />
             <intent-filter>
                 <action android:name="android.intent.action.MAIN"/>
                 <category android:name="android.intent.category.LAUNCHER"/>

example/android/app/src/main/java/com/mr/flutter/plugin/filepickerexample/MainActivity.java

@@ -1,13 +1,5 @@
 package com.mr.flutter.plugin.filepicker.example;
 
-import android.os.Bundle;
+import io.flutter.embedding.android.FlutterActivity;
-import io.flutter.app.FlutterActivity;
-import io.flutter.plugins.GeneratedPluginRegistrant;
 
-public class MainActivity extends FlutterActivity {
+public class MainActivity extends FlutterActivity { }
-  @Override
-  protected void onCreate(Bundle savedInstanceState) {
-    super.onCreate(savedInstanceState);
-    GeneratedPluginRegistrant.registerWith(this);
-  }
-}

example/ios/Flutter/Flutter.podspec

@@ -1,18 +0,0 @@
-#
-# NOTE: This podspec is NOT to be published. It is only used as a local source!
-#
-
-Pod::Spec.new do |s|
-  s.name             = 'Flutter'
-  s.version          = '1.0.0'
-  s.summary          = 'High-performance, high-fidelity mobile apps.'
-  s.description      = <<-DESC
-Flutter provides an easy and productive way to build and deploy high-performance mobile apps for Android and iOS.
-                       DESC
-  s.homepage         = 'https://flutter.io'
-  s.license          = { :type => 'MIT' }
-  s.author           = { 'Flutter Dev Team' => 'flutter-dev@googlegroups.com' }
-  s.source           = { :git => 'https://github.com/flutter/engine', :tag => s.version.to_s }
-  s.ios.deployment_target = '8.0'
-  s.vendored_frameworks = 'Flutter.framework'
-end

example/lib/src/file_picker_demo.dart

@@ -196,7 +196,7 @@ class _FilePickerDemoState extends State<FilePickerDemo> {
                                               ? _paths!
                                                   .map((e) => e.name)
                                                   .toList()[index]
-                                              : _fileName ?? '...')!;
+                                              : _fileName ?? '...');
                                       final path = _paths!
                                           .map((e) => e.path)
                                           .toList()[index]

lib/src/file_picker.dart

@@ -46,28 +46,35 @@ abstract class FilePicker extends PlatformInterface {
   /// Default [type] set to [FileType.any] with [allowMultiple] set to [false]
   /// Optionally, [allowedExtensions] might be provided (e.g. `[pdf, svg, jpg]`.).
   ///
-  /// If [withData] is set, picked files will have its byte data immediately available on memory as [Uint8List]
+  /// If [withData] is set, picked files will have its byte data immediately available on memory as `Uint8List`
-  /// which can be useful if you are picking it for server upload or similar.
+  /// which can be useful if you are picking it for server upload or similar. However, have in mind that
+  /// enabling this on IO (iOS & Android) may result in out of memory issues if you allow multiple picks or
+  /// pick huge files. Use [withReadStream] instead. Defaults to `true` on web, `false` otherwise.
   ///
   /// If [withReadStream] is set, picked files will have its byte data available as a [Stream<List<int>>]
-  /// which can be useful for uploading and processing large files.
+  /// which can be useful for uploading and processing large files. Defaults to `false`.
   ///
   /// If you want to track picking status, for example, because some files may take some time to be
   /// cached (particularly those picked from cloud providers), you may want to set [onFileLoading] handler
   /// that will give you the current status of picking.
   ///
+  /// If [allowCompression] is set, it will allow media to apply the default OS compression.
+  /// Defaults to `true`.
+  ///
   /// The result is wrapped in a [FilePickerResult] which contains helper getters
   /// with useful information regarding the picked [List<PlatformFile>].
   ///
+  /// For more information, check the [API documentation](https://github.com/miguelpruivo/flutter_file_picker/wiki/api).
+  ///
   /// Returns [null] if aborted.
   Future<FilePickerResult?> pickFiles({
     FileType type = FileType.any,
     List<String>? allowedExtensions,
     Function(FilePickerStatus)? onFileLoading,
-    bool? allowCompression,
+    bool allowCompression = true,
     bool allowMultiple = false,
-    bool? withData,
+    bool withData = false,
-    bool? withReadStream,
+    bool withReadStream = false,
   }) async =>
       throw UnimplementedError('pickFiles() has not been implemented.');
 
@@ -78,13 +85,13 @@ abstract class FilePicker extends PlatformInterface {
   /// of it whenever needed. However, this will force the cleanup if you want to manage those on your own.
   ///
   /// Returns [true] if the files were removed with success, [false] otherwise.
-  Future<bool?> clearTemporaryFiles() async => throw UnimplementedError(
+  Future<bool?> clearTemporaryFiles() async => throw UnimplementedError('clearTemporaryFiles() has not been implemented.');
-      'clearTemporaryFiles() has not been implemented.');
 
   /// Selects a directory and returns its absolute path.
   ///
   /// On Android, this requires to be running on SDK 21 or above, else won't work.
   /// Returns [null] if folder path couldn't be resolved.
-  Future<String?> getDirectoryPath() async =>
+  ///
-      throw UnimplementedError('getDirectoryPath() has not been implemented.');
+  /// Note: Some Android paths are protected, hence can't be accessed and will return `/` instead.
+  Future<String?> getDirectoryPath() async => throw UnimplementedError('getDirectoryPath() has not been implemented.');
 }

lib/src/file_picker_io.dart

@@ -70,9 +70,9 @@ class FilePickerIO extends FilePicker {
     bool? withReadStream,
   ) async {
     final String type = describeEnum(fileType);
-    if (type != 'custom' && (allowedExtensions?.isNotEmpty ?? false)) {
+    if (type != FileType.custom && (allowedExtensions?.isNotEmpty ?? false)) {
       throw Exception(
-          'If you are using a custom extension filter, please use the FileType.custom instead.');
+          'You are setting a type [$fileType]. Custom extension filters are only allowed with FileType.custom, please change it or remove filters.');
     }
     try {
       _eventSubscription?.cancel();
@@ -98,7 +98,7 @@ class FilePickerIO extends FilePicker {
 
       final List<PlatformFile> platformFiles = <PlatformFile>[];
 
-      for (final platformFileMap in result) {
+      for (final Map platformFileMap in result) {
         platformFiles.add(
           PlatformFile.fromMap(
             platformFileMap,

lib/src/file_picker_web.dart

@@ -47,6 +47,11 @@ class FilePickerWeb extends FilePicker {
     bool? withData = true,
     bool? withReadStream = false,
   }) async {
+    if (type != FileType.custom && (allowedExtensions?.isNotEmpty ?? false)) {
+      throw Exception(
+          'You are setting a type [$type]. Custom extension filters are only allowed with FileType.custom, please change it or remove filters.');
+    }
+
     final Completer<List<PlatformFile>?> filesCompleter =
         Completer<List<PlatformFile>?>();
 

lib/src/platform_file.dart

@@ -3,11 +3,11 @@ import 'dart:typed_data';
 
 class PlatformFile {
   const PlatformFile({
+    required this.name,
+    required this.size,
     this.path,
-    this.name,
     this.bytes,
     this.readStream,
-    this.size,
   });
 
   PlatformFile.fromMap(Map data, {this.readStream})
@@ -21,21 +21,24 @@ class PlatformFile {
   /// ```
   /// final File myFile = File(platformFile.path);
   /// ```
+  /// On web this is always `null`. You should access `bytes` property instead.
+  /// Read more about it [here](https://github.com/miguelpruivo/flutter_file_picker/wiki/FAQ)
   final String? path;
 
   /// File name including its extension.
-  final String? name;
+  final String name;
 
   /// Byte data for this file. Particurlarly useful if you want to manipulate its data
   /// or easily upload to somewhere else.
+  /// [Check here in the FAQ](https://github.com/miguelpruivo/flutter_file_picker/wiki/FAQ) an example on how to use it to upload on web.
   final Uint8List? bytes;
 
   /// File content as stream
   final Stream<List<int>>? readStream;
 
   /// The file size in bytes.
-  final int? size;
+  final int size;
 
   /// File extension for this file.
-  String? get extension => name?.split('.').last;
+  String? get extension => name.split('.').last;
 }

pubspec.yaml

@@ -1,7 +1,7 @@
 name: file_picker
 description: A package that allows you to use a native file explorer to pick single or multiple absolute file paths, with extension filtering support.
 homepage: https://github.com/miguelpruivo/plugins_flutter_file_picker
-version: 3.0.1
+version: 3.0.2
 
 dependencies:
   flutter: