From 7b3a34064c27056865cebd5074b4735d75ba97e7 Mon Sep 17 00:00:00 2001 From: Vick Top Date: Tue, 20 Feb 2024 13:28:59 +0100 Subject: [PATCH] doc: create documentation for files --- lib/src/utils/form_page_controller.dart | 7 ++++++ lib/src/utils/formstate.dart | 4 ++++ .../input_date_picker/input_date_picker.dart | 22 +++++++++++++++++ .../input/input_types/input_email.dart | 10 ++++++++ .../input_number_picker.dart | 10 ++++++++ .../input_password/input_password.dart | 8 ++++++- .../input/input_types/input_plain_text.dart | 24 +++++++++++++++++++ .../input_slider/input_slider.dart | 12 ++++++++++ .../input_switch/input_switch.dart | 6 +++++ 9 files changed, 102 insertions(+), 1 deletion(-) diff --git a/lib/src/utils/form_page_controller.dart b/lib/src/utils/form_page_controller.dart index af0b823..a317f65 100644 --- a/lib/src/utils/form_page_controller.dart +++ b/lib/src/utils/form_page_controller.dart @@ -4,20 +4,26 @@ import 'package:flutter_form_wizard/flutter_form.dart'; +/// Controller class for managing input controllers in a Flutter form. class FlutterFormPageController { + /// List of input controllers. List _controllers = []; + /// Registers an input controller. void register(FlutterFormInputController inputController) { _controllers.add(inputController); } + /// Clears all registered input controllers. void clearControllers() { _controllers = []; } + /// Checks if an input controller is registered with a given ID. bool _isRegisteredById(String id) => _controllers.any((element) => element.id == id); + /// Retrieves the input controller associated with the provided ID. FlutterFormInputController? getController(String key) { if (_isRegisteredById(key)) { return _controllers.firstWhere((element) => element.id == key); @@ -25,6 +31,7 @@ class FlutterFormPageController { return null; } + /// Retrieves all values from registered input controllers. Map getAllValues() { var values = {}; diff --git a/lib/src/utils/formstate.dart b/lib/src/utils/formstate.dart index 69f3fc4..06a0e1b 100644 --- a/lib/src/utils/formstate.dart +++ b/lib/src/utils/formstate.dart @@ -5,15 +5,19 @@ import 'package:flutter/material.dart'; import 'package:flutter_form_wizard/src/utils/form_page_controller.dart'; +/// Widget for managing form state and providing access to form controller. class FormState extends InheritedWidget { + /// Constructor for FormState. const FormState({ required super.child, required this.formController, super.key, }); + /// The form controller associated with this FormState. final FlutterFormPageController formController; + /// Retrieves the nearest ancestor FormState from the given context. static FormState of(BuildContext context) { var result = context.dependOnInheritedWidgetOfExactType(); assert(result != null, 'No FormStat found in context'); diff --git a/lib/src/widgets/input/input_types/input_date_picker/input_date_picker.dart b/lib/src/widgets/input/input_types/input_date_picker/input_date_picker.dart index 323f6c5..b3018a9 100644 --- a/lib/src/widgets/input/input_types/input_date_picker/input_date_picker.dart +++ b/lib/src/widgets/input/input_types/input_date_picker/input_date_picker.dart @@ -13,6 +13,22 @@ import 'package:intl/intl.dart'; /// /// Standard controller is [FlutterFormInputDateController]. class FlutterFormInputDateTime extends FlutterFormInputWidget { + /// Creates a [FlutterFormInputDateTime]. + /// + /// The [controller], [inputType], [dateFormat] are required parameters. + /// The [label] parameter specifies the label of the input field. + /// The [showIcon] parameter determines whether to show an icon + /// with the input field. + /// The [firstDate] and [lastDate] parameters specify the range + /// of selectable dates. + /// The [initialDate] parameter specifies the initial date for + /// the input field. + /// The [initialDateTimeRange] parameter specifies the initial + /// date time range for the input field. + /// The [icon] parameter specifies the icon to show with the input field. + /// The [enabled] parameter specifies whether the input field is enabled. + /// The [onTapEnabled] parameter specifies whether tapping on + /// the input field is enabled. const FlutterFormInputDateTime({ required super.controller, required this.inputType, @@ -70,6 +86,12 @@ class FlutterFormInputDateTime extends FlutterFormInputWidget { /// Mainly used by [FlutterFormInputDateTime]. class FlutterFormInputDateTimeController implements FlutterFormInputController { + /// Creates a [FlutterFormInputDateTimeController]. + /// + /// The [id], [dateTimeType], and [dateFormat] are required parameters. + /// The [mandatory] parameter specifies whether the input is mandatory. + /// The [value], [initialDate], [initialDateTimeRange], [checkPageTitle], + /// [checkPageDescription], and [onChanged] parameters are optional. FlutterFormInputDateTimeController({ required this.id, required this.dateTimeType, diff --git a/lib/src/widgets/input/input_types/input_email.dart b/lib/src/widgets/input/input_types/input_email.dart index e99fac2..19db0dd 100644 --- a/lib/src/widgets/input/input_types/input_email.dart +++ b/lib/src/widgets/input/input_types/input_email.dart @@ -10,6 +10,10 @@ import 'package:flutter_input_library/flutter_input_library.dart' as input; /// /// Standard controller is [FlutterFormInputEmailController]. class FlutterFormInputEmail extends FlutterFormInputWidget { + /// Creates a [FlutterFormInputEmail]. + /// + /// The [controller] parameter is required. + /// The [key], [focusNode], [label], and [enabled] parameters are optional. const FlutterFormInputEmail({ required super.controller, super.key, @@ -49,6 +53,12 @@ class FlutterFormInputEmail extends FlutterFormInputWidget { /// Mainly used by [FlutterFormInputEmail]. class FlutterFormInputEmailController implements FlutterFormInputController { + /// Creates a [FlutterFormInputEmailController]. + /// + /// The [id] parameter specifies the unique identifier for the controller. + /// The [mandatory] parameter specifies whether the input is mandatory. + /// The [value], [checkPageTitle], [checkPageDescription], [onChanged], + /// and [onSubmit] parameters are optional. FlutterFormInputEmailController({ required this.id, this.mandatory = true, diff --git a/lib/src/widgets/input/input_types/input_number_picker/input_number_picker.dart b/lib/src/widgets/input/input_types/input_number_picker/input_number_picker.dart index c74a803..458fdc3 100644 --- a/lib/src/widgets/input/input_types/input_number_picker/input_number_picker.dart +++ b/lib/src/widgets/input/input_types/input_number_picker/input_number_picker.dart @@ -41,8 +41,18 @@ class FlutterFormInputNumberPicker extends FlutterFormInputWidget { } } +/// Controller for numbers used by a [FlutterFormInputWidget] used in a +/// [FlutterForm]. +/// +/// Mainly used by [FlutterFormInputNumberPicker]. class FlutterFormInputNumberPickerController implements FlutterFormInputController { + /// Creates a [FlutterFormInputNumberPickerController]. + /// + /// The [id] parameter specifies the unique identifier for the controller. + /// The [mandatory] parameter specifies whether the input is mandatory. + /// The [value], [checkPageTitle], [checkPageDescription], + /// and [onChanged] parameters are optional. FlutterFormInputNumberPickerController({ required this.id, this.mandatory = true, diff --git a/lib/src/widgets/input/input_types/input_password/input_password.dart b/lib/src/widgets/input/input_types/input_password/input_password.dart index 357abe2..6ad919e 100644 --- a/lib/src/widgets/input/input_types/input_password/input_password.dart +++ b/lib/src/widgets/input/input_types/input_password/input_password.dart @@ -44,6 +44,12 @@ class FlutterFormInputPassword extends FlutterFormInputWidget { /// Mainly used by [FlutterFormInputPassword]. class FlutterFormInputPasswordController implements FlutterFormInputController { + /// Creates a [FlutterFormInputPasswordController]. + /// + /// The [id] parameter specifies the unique identifier for the controller. + /// The [mandatory] parameter specifies whether the input is mandatory. + /// The [value], [checkPageTitle], [checkPageDescription], [onChanged], + /// and [onSubmit] parameters are optional. FlutterFormInputPasswordController({ required this.id, this.mandatory = true, @@ -91,7 +97,7 @@ class FlutterFormInputPasswordController } if (value.length < 6) { - return translator('Field should be atleast 6 characters long'); + return translator('Field should be at least 6 characters long'); } } diff --git a/lib/src/widgets/input/input_types/input_plain_text.dart b/lib/src/widgets/input/input_types/input_plain_text.dart index 0a54fb2..dadc4fd 100644 --- a/lib/src/widgets/input/input_types/input_plain_text.dart +++ b/lib/src/widgets/input/input_types/input_plain_text.dart @@ -12,6 +12,12 @@ import 'package:flutter_input_library/flutter_input_library.dart' as input; /// /// Standard controller is [FlutterFormInputPlainTextController]. class FlutterFormInputPlainText extends FlutterFormInputWidget { + /// Creates a [FlutterFormInputPlainText]. + /// + /// The [controller] parameter is required. + /// The [key], [focusNode], [label], [decoration], [textAlignVertical], + /// [expands], [maxLines], [scrollPadding], [maxLength], [keyboardType], + /// [enabled], [style], and [textCapitalization] parameters are optional. const FlutterFormInputPlainText({ required super.controller, super.key, @@ -92,13 +98,25 @@ class FlutterFormInputMultiLine extends StatelessWidget { this.textCapitalization = TextCapitalization.sentences, }); + /// The controller for the multi-line input. final FlutterFormInputController controller; + + /// The optional label widget for the input. final Widget? label; + + /// The optional focus node for the input. final FocusNode? focusNode; + /// The optional hint text displayed inside the input field. final String? hint; + + /// The optional maximum number of characters allowed in the input field. final int? maxCharacters; + + /// A flag indicating whether the input field is enabled. final bool enabled; + + /// The capitalization behavior for the input field. final TextCapitalization textCapitalization; @override @@ -126,6 +144,12 @@ class FlutterFormInputMultiLine extends StatelessWidget { /// Mainly used by [FlutterFormInputPlainText]. class FlutterFormInputPlainTextController implements FlutterFormInputController { + /// Creates a [FlutterFormInputPlainTextController]. + /// + /// The [id] parameter specifies the unique identifier for the controller. + /// The [mandatory] parameter specifies whether the input is mandatory. + /// The [value], [checkPageTitle], [checkPageDescription], [onChanged], + /// and [onSubmit] parameters are optional. FlutterFormInputPlainTextController({ required this.id, this.mandatory = false, diff --git a/lib/src/widgets/input/input_types/input_slider/input_slider.dart b/lib/src/widgets/input/input_types/input_slider/input_slider.dart index 1eab5d5..31ce3aa 100644 --- a/lib/src/widgets/input/input_types/input_slider/input_slider.dart +++ b/lib/src/widgets/input/input_types/input_slider/input_slider.dart @@ -11,6 +11,12 @@ import 'package:flutter_input_library/flutter_input_library.dart' as input; /// /// Standard controller is [FlutterFormInputSliderController]. class FlutterFormInputSlider extends FlutterFormInputWidget { + /// Creates a [FlutterFormInputPassword]. + /// + /// The [controller] parameter is required. + /// The [focusNode] parameter specifies the focus node of the input field. + /// The [label] parameter specifies the label of the input field. + /// The [enabled] parameter specifies whether the input field is enabled. const FlutterFormInputSlider({ required super.controller, super.key, @@ -43,6 +49,12 @@ class FlutterFormInputSlider extends FlutterFormInputWidget { /// Mainly used by [FlutterFormInputSlider]. class FlutterFormInputSliderController implements FlutterFormInputController { + /// Creates a [FlutterFormInputPasswordController]. + /// + /// The [id] parameter specifies the unique identifier for the controller. + /// The [mandatory] parameter specifies whether the input is mandatory. + /// The [value], [checkPageTitle], [checkPageDescription], [onChanged], + /// and [onSubmit] parameters are optional. FlutterFormInputSliderController({ required this.id, this.mandatory = true, diff --git a/lib/src/widgets/input/input_types/input_switch/input_switch.dart b/lib/src/widgets/input/input_types/input_switch/input_switch.dart index 042b304..3a3eb3b 100644 --- a/lib/src/widgets/input/input_types/input_switch/input_switch.dart +++ b/lib/src/widgets/input/input_types/input_switch/input_switch.dart @@ -42,6 +42,12 @@ class FlutterFormInputSwitch extends FlutterFormInputWidget { /// Mainly used by [FlutterFormInputSwitch]. class FlutterFormInputSwitchController implements FlutterFormInputController { + /// Creates a [FlutterFormInputSwitchController]. + /// + /// The [id] parameter specifies the unique identifier for the controller. + /// The [mandatory] parameter specifies whether the input is mandatory. + /// The [value], [checkPageTitle], [checkPageDescription], + /// and [onChanged] parameters are optional. FlutterFormInputSwitchController({ required this.id, this.mandatory = true,