From cee3bd2293bafb871009bf6907c4e8ab624c2049 Mon Sep 17 00:00:00 2001 From: commitimpush Date: Thu, 1 Sep 2022 10:22:32 +0200 Subject: [PATCH] added documentation in the code --- example/lib/main.dart | 17 ++++++++++++++--- lib/image_picker.dart | 19 ++++++++++++++++++- lib/src/models/image_picker_settings.dart | 2 ++ lib/src/services/image_picker_service.dart | 3 +++ lib/src/ui/image_picker_ui.dart | 21 ++++++++++++++++++--- 5 files changed, 55 insertions(+), 7 deletions(-) diff --git a/example/lib/main.dart b/example/lib/main.dart index 0edf609..be8ead6 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -41,6 +41,9 @@ class _ImagePickerExampleHomePageState final ImagePicker imagePicker = ImagePicker(); final double whiteSpace = 20; final double imageWidth = 300; + final String placeholder = 'assets/images/placeholder.png'; + final String imageAlreadyDisplayedMessage = + 'Selected image is already being displayed!'; @override Widget build(BuildContext context) { @@ -56,7 +59,7 @@ class _ImagePickerExampleHomePageState Column(children: [ if (image == null) ...[ Image.asset( - 'assets/images/placeholder.png', + placeholder, width: imageWidth, height: imageWidth, ) @@ -83,6 +86,14 @@ class _ImagePickerExampleHomePageState ); } + /// The [pickImage] function is used to show the usage of the Image Picker Package. + /// The most important part is the [showImagePickerDialog] function call. + /// The only required parameter is the [context] of the application. + /// There are multiple optional parameters that can be included to customize the Image Picker Dialog. + /// You can add an optional parameter by for example adding [title: "Image Picker"] to the function call after the context parameter. + /// Check the README for all possible optional parameters you can add. + /// This function saves the image in a variable and if it's different than the current image it will get displayed in the application. + /// When the same image is chosen there will be a snackbar popping up to let you know it's already being displayed. void pickImage() async { Uint8List? imageInBytes = await imagePicker.showImagePickerDialog(context); if (imageInBytes != null) { @@ -91,9 +102,9 @@ class _ImagePickerExampleHomePageState image = imageInBytes; }); } else { + if (!mounted) return; ScaffoldMessenger.of(context).showSnackBar( - const SnackBar( - content: Text('Selected image is already being displayed!')), + SnackBar(content: Text(imageAlreadyDisplayedMessage)), ); } } diff --git a/lib/image_picker.dart b/lib/image_picker.dart index 8e04686..dbddf5c 100644 --- a/lib/image_picker.dart +++ b/lib/image_picker.dart @@ -5,14 +5,31 @@ import 'src/models/image_picker_settings.dart'; import 'src/ui/image_picker_ui.dart'; class ImagePicker { + /// [showImagePickerDialog] is the function that gets called by the user of the package. + /// With this function the Image Picker Dialog gets shown and can be used to pick an image. + /// The image gets returned as a [Uint8List] and can be used in the application. + /// It can also return null when there is no image selected. + /// The function has one required parameter and multiple optional parameters to customize the Image Picker Dialog. + /// The only required parameter is [context] which is the [BuildContext] of the application. + /// Then you can give the following optional parameters to customize the Image Picker Dialog: + /// [title] expects a [String] that is used as the title of the Image Picker Dialog and will be showed at the top of it. + /// [titleTextSize] is the font size of the [title]. + /// [iconSize] is the size of each icon shown in the Image Picker Dialog. + /// [iconTextSize] is the size of the text that's show underneath the icon. + /// [spaceBetweenIcons] is the size of the space that's between the two icons in the Image Picker Dialog. + /// [makePhotoIcon] is the icon as [IconData] that's shown for the make photo button of the Image Picker Dialog. + /// [makePhotoText] is the text that's shown underneath the make photo button in the Image Picker Dialog. + /// [selectImageIcon] is the icon as [IconData] that's shown for the select image button of the Image Picker Dialog. + /// [selectImageText] is the text that's shown underneath the select image button in the Image Picker Dialog. + /// [closeButtonText] is the text that's shown on the close dialog button on the bottom of the Image Picker Dialog. Future showImagePickerDialog(BuildContext context, {String title = ImagePickerDefaultParameters.title, double titleTextSize = ImagePickerDefaultParameters.titleTextSize, double iconSize = ImagePickerDefaultParameters.iconSize, double iconTextSize = ImagePickerDefaultParameters.iconTextSize, double spaceBetweenIcons = ImagePickerDefaultParameters.spaceBetweenIcons, - String makePhotoText = ImagePickerDefaultParameters.makePhotoText, IconData makePhotoIcon = ImagePickerDefaultParameters.makePhotoIcon, + String makePhotoText = ImagePickerDefaultParameters.makePhotoText, IconData selectImageIcon = ImagePickerDefaultParameters.selectImageIcon, String selectImageText = ImagePickerDefaultParameters.selectImageText, String closeButtonText = ImagePickerDefaultParameters.closeButtonText}) { diff --git a/lib/src/models/image_picker_settings.dart b/lib/src/models/image_picker_settings.dart index d402b47..6bb1109 100644 --- a/lib/src/models/image_picker_settings.dart +++ b/lib/src/models/image_picker_settings.dart @@ -1,5 +1,7 @@ import 'package:flutter/material.dart'; +/// Default values for all the possible optional parameters to be included in the function call when opening the Image Picker Dialog. +/// When the function call has no optional parameters included these values will be used. class ImagePickerDefaultParameters { static const String title = "Upload Image"; static const double titleTextSize = 20; diff --git a/lib/src/services/image_picker_service.dart b/lib/src/services/image_picker_service.dart index 29ef94a..ce0a505 100644 --- a/lib/src/services/image_picker_service.dart +++ b/lib/src/services/image_picker_service.dart @@ -4,6 +4,9 @@ import 'package:image_picker/image_picker.dart'; class ImagePickerService { final ImagePicker _imagePicker = ImagePicker(); + /// [pickImage] is the function that picks the image and returns it when the Image Picker Dialog gets closed. + /// The function requires [source], an [ImageSource] that's the method of how the image needs to be picked, for example gallery or camera. + /// It also requires [context], the [BuildContext] which is needed to be able to return the image when the Image Picker Dialog gets closed. void pickImage(ImageSource source, BuildContext context) async { var image = await (await _imagePicker.pickImage(source: source))?.readAsBytes(); diff --git a/lib/src/ui/image_picker_ui.dart b/lib/src/ui/image_picker_ui.dart index 7abb08d..28c965b 100644 --- a/lib/src/ui/image_picker_ui.dart +++ b/lib/src/ui/image_picker_ui.dart @@ -7,6 +7,13 @@ import 'package:image_picker/image_picker.dart'; class ImagePickerUI { final ImagePickerService _imagePickerService = ImagePickerService(); + /// [pickImageDialog] returns a [ModalBottomSheet] widget that displays two icons. + /// When clicked on the left icon the user can pick an image from their documents on their phone. + /// When clicked on the right icon the user can make a photo with the camera on their phone. + /// The function gets all the parameters from the [image_picker] class where a function provides them all. + /// See that function for a description of each parameter. + /// The [pickImageDialog] function can return a [Uint8List] that is the picked image as a bytes list. + /// It can also return null when no image gets chosen. Future pickImageDialog( BuildContext context, String title, @@ -35,12 +42,12 @@ class ImagePickerUI { Row( mainAxisAlignment: MainAxisAlignment.center, children: [ - generateIconButtonWithText(context, selectImageIcon, iconSize, + _generateIconButtonWithText(context, selectImageIcon, iconSize, iconTextSize, ImageSource.gallery, selectImageText), SizedBox( width: spaceBetweenIcons, ), - generateIconButtonWithText(context, makePhotoIcon, iconSize, + _generateIconButtonWithText(context, makePhotoIcon, iconSize, iconTextSize, ImageSource.camera, makePhotoText), ], ), @@ -65,7 +72,15 @@ class ImagePickerUI { ); } - Column generateIconButtonWithText( + /// The [_generateIconButtonWithText] function returns a column that includes an [IconButton] and [Text]. + /// The function requires the following parameters to be able to generate an icon with text: + /// [context] The build context that is required to make the [pickImage] function in [_imagePickerService] work. + /// [icon] The icon that needs to be displayed, requires an [IconData] as value to be used. + /// [iconSize] The size of the icon. + /// [iconTextSize] The size of the text that's displayed underneath the icon. + /// [imageSource] The type of [ImageSource] to be used to pick an image when pressed on the icon. + /// [bottomText] The text that's displayed underneath the icon. + Column _generateIconButtonWithText( BuildContext context, IconData icon, double iconSize,