From 992bd98d3ecd2dfa164ef2adc4bacd0ab79ed79a Mon Sep 17 00:00:00 2001 From: netharu methmitha Date: Fri, 6 May 2022 21:35:44 +0530 Subject: [PATCH] added documentation --- lib/db_handler.dart | 25 +++++++++- lib/inheited_widgets.dart | 3 ++ lib/main.dart | 2 + lib/models/bell.dart | 5 +- lib/pages/bell_add_page.dart | 6 ++- lib/pages/bell_editor.dart | 20 +++++++- lib/pages/bell_errors_page.dart | 14 +++--- lib/pages/bells_page.dart | 81 +++++++++++++++------------------ lib/pages/settings_page.dart | 8 ++++ lib/settings.dart | 11 +++++ lib/widgets/bell_card.dart | 23 ++++++++-- lib/widgets/select_days.dart | 1 + lib/widgets/title_bar.dart | 39 ++++++++++++++++ 13 files changed, 173 insertions(+), 65 deletions(-) diff --git a/lib/db_handler.dart b/lib/db_handler.dart index 2c5faf2..011ed3b 100644 --- a/lib/db_handler.dart +++ b/lib/db_handler.dart @@ -6,11 +6,14 @@ import 'package:path/path.dart'; class DBHandler { DBHandler._init(); + + /// instance of the [DBHandler] static final DBHandler instance = DBHandler._init(); static Database? _database; Future get database async => _database ??= await _initDB(); + /// initializes the [Database] Future _initDB() async { sqfliteFfiInit(); String pathToDb = await getApplicationDocumentsDirectory().then((dir) { @@ -22,6 +25,7 @@ class DBHandler { ); } + /// this will execute a sql commands to create the databases Future _onCreate(Database db, int version) async { await db.execute(''' CREATE TABLE bells ( @@ -37,6 +41,8 @@ class DBHandler { '''); } + /// returns bells as a [List] of [Map]s `List>` + /// - this also sorts the bells by there position or order Future>> getBells() async { final Database db = await database; List> map = [ @@ -47,14 +53,20 @@ class DBHandler { return map; } + /// inserts a [Bell] into the database Future insertBell(Bell bell) async { final Database db = await database; return await db.insert( 'bells', bell.toMap(boolToInt: true, listToString: true)); } - /// - /// @param deactivate - enable or disable the process of deactivating bell when updating + /// updates a bell in the dataBase + /// - [bell] - a bell with updated parameters make sure that `id` is available in the bell + /// - lets say you wanna update the title of a bell + /// - ```dart + /// updateBell(someBell..title = "someNewTitle"); + /// ``` + /// - [dispose] - enable or disable the process of deactivating bell when updating /// Future updateBell(Bell bell, {bool dispose = true}) async { final Database db = await database; @@ -66,6 +78,7 @@ class DBHandler { where: 'id = ?', whereArgs: [bell.id]); } + /// moves a bell from a [prevPos] to a [newPos] in the dataBase Future moveBell(int prevPos, int newPos) async { List> bellMaps = await getBells(); prevPos = bellMaps[prevPos]['position']; @@ -88,6 +101,13 @@ class DBHandler { } } + /// fixes the messed up bell positions + /// + /// when you delete a bell bell there are gaps between bell positions - `[0,1,2,4,5]` + /// + /// `3` is missing + /// + /// this will fix the bell positions to `[0,1,2,3,4]` Future fixBellPositions() async { List> bellsMap = await getBells(); for (var i = 0; i < bellsMap.length; i++) { @@ -98,6 +118,7 @@ class DBHandler { } } + /// deletes a [Bell] Future deleteBell(Bell bell) async { final Database db = await database; bell.deactivateBell(); diff --git a/lib/inheited_widgets.dart b/lib/inheited_widgets.dart index 9a77f24..9147c77 100644 --- a/lib/inheited_widgets.dart +++ b/lib/inheited_widgets.dart @@ -1,11 +1,14 @@ import 'package:flutter/material.dart'; +/// inherited widget for the [BellCard] this will provide data needed for [BellCard] class BellCardData extends InheritedWidget { const BellCardData({required this.shake, Key? key, required Widget child}) : super(child: child, key: key); + /// if [BellCard] needs to shake it needs to be [true] otherwise [false] final bool shake; + /// picks the bellCardData from the [context] static BellCardData of(BuildContext context) { final BellCardData? result = context.dependOnInheritedWidgetOfExactType(); diff --git a/lib/main.dart b/lib/main.dart index fae3801..07909d3 100644 --- a/lib/main.dart +++ b/lib/main.dart @@ -125,6 +125,8 @@ class _MyAppState extends State with WindowListener { }), ), tooltipTheme: TooltipThemeData( + showDuration: + const Duration(), //setting the show duration to minimum as possible decoration: BoxDecoration( color: const Color(0xff32363d), borderRadius: BorderRadius.circular(8), diff --git a/lib/models/bell.dart b/lib/models/bell.dart index d85f4a1..18078c3 100644 --- a/lib/models/bell.dart +++ b/lib/models/bell.dart @@ -25,6 +25,7 @@ class BellErrorExtended { @override bool operator ==(dynamic other) { + if (runtimeType != other.runtimeType) return false; return error == other.error; } } @@ -153,8 +154,8 @@ class Bell { /// this will look at the week days before activating /// /// so if you wanna force the activation set - /// - @param force to [true] its [false] by default - /// - @param disableTimer - disables the activation of the timer + /// - @param [force] to [true] its [false] by default + /// - @param [disableTimer] - disables the activation of the timer Future activateBell({ bool force = false, bool disableTimer = false, diff --git a/lib/pages/bell_add_page.dart b/lib/pages/bell_add_page.dart index 00c9a04..ba8a002 100644 --- a/lib/pages/bell_add_page.dart +++ b/lib/pages/bell_add_page.dart @@ -15,12 +15,14 @@ class _AddNewBellPageState extends State { bool _filled = false; TimeOfDay? _time; + /// returns [true] if every parameter is filled bool _checkFilled() { if (_titleController.text == "") return false; if (_time == null) return false; return true; } + /// looking for ability to save void _checkForSave() { setState(() { _filled = _checkFilled(); @@ -76,7 +78,7 @@ class _AddNewBellPageState extends State { ), Expanded( child: TextField( - onChanged: (value) { + onChanged: (_) { _checkForSave(); }, decoration: const InputDecoration( @@ -99,7 +101,7 @@ class _AddNewBellPageState extends State { ), Expanded( child: TextField( - onChanged: (value) { + onChanged: (_) { _checkForSave(); }, decoration: const InputDecoration( diff --git a/lib/pages/bell_editor.dart b/lib/pages/bell_editor.dart index ba7676f..0868df7 100644 --- a/lib/pages/bell_editor.dart +++ b/lib/pages/bell_editor.dart @@ -16,12 +16,23 @@ class BellEditingPage extends StatefulWidget { class _BellEditingPageState extends State { final TextEditingController _titleController = TextEditingController(); final TextEditingController _descController = TextEditingController(); + + /// if anything has changed bool _changed = false; + + /// whether everything is filled or not bool _filled = true; + + /// time of the [Bell] late TimeOfDay? _time; + + /// list of weekDays late List _days; + + /// audio path of the [Bell] String? _audioPath; + /// returns [true] if every necessary is filled other wise [false] bool _checkFilled() { if (_titleController.text == "") return false; if (_time == null) return false; @@ -40,6 +51,7 @@ class _BellEditingPageState extends State { super.initState(); } + /// returns [true] if any parameter has changed otherwise [false] bool _checkChanged() { if (_titleController.text != (widget.bell.title ?? "")) return true; if (_descController.text != (widget.bell.description ?? "")) return true; @@ -49,6 +61,9 @@ class _BellEditingPageState extends State { return false; } + /// checks for saving ability + /// - every thing needs to be filled in properly + /// - and atleast one parameter has to be changed void _checkForSave() { setState(() { _changed = _checkChanged(); @@ -145,7 +160,7 @@ class _BellEditingPageState extends State { ), Expanded( child: TextField( - onChanged: (value) { + onChanged: (_) { _checkForSave(); }, decoration: const InputDecoration( @@ -168,7 +183,7 @@ class _BellEditingPageState extends State { ), Expanded( child: TextField( - onChanged: (value) { + onChanged: (_) { _checkForSave(); }, keyboardType: TextInputType.multiline, @@ -268,6 +283,7 @@ class _BellEditingPageState extends State { } } +/// [AlertDialog] when user tries to go back without saving changes AlertDialog confirmationDialog({Function()? onDiscard, Function()? onCancel}) { return AlertDialog( backgroundColor: Colors.black, diff --git a/lib/pages/bell_errors_page.dart b/lib/pages/bell_errors_page.dart index 338b883..7986c9f 100644 --- a/lib/pages/bell_errors_page.dart +++ b/lib/pages/bell_errors_page.dart @@ -3,15 +3,13 @@ import 'package:auto_bell/widgets/title_bar.dart'; import 'package:flutter/material.dart'; import 'package:url_launcher/url_launcher.dart'; -class BellErrorsPage extends StatefulWidget { +/// shows errors of a [Bell] +/// - [bellErrors] errors of the [Bell] +class BellErrorsPage extends StatelessWidget { + /// errors of the [Bell] final BellErrors bellErrors; const BellErrorsPage({Key? key, required this.bellErrors}) : super(key: key); - @override - State createState() => _BellErrorsPageState(); -} - -class _BellErrorsPageState extends State { @override Widget build(BuildContext context) { return Scaffold( @@ -30,7 +28,7 @@ class _BellErrorsPageState extends State { mainAxisAlignment: MainAxisAlignment.spaceBetween, children: [ Text( - 'Errors on bell "${widget.bellErrors.parent.title}"', + 'Errors on bell "${bellErrors.parent.title}"', style: const TextStyle( fontWeight: FontWeight.bold, fontSize: 20, @@ -59,7 +57,7 @@ class _BellErrorsPageState extends State { Expanded( child: ListView( children: [ - for (var bellError in widget.bellErrors.getErrorsList) + for (var bellError in bellErrors.getErrorsList) BellErrorWidget( bellError: bellError, ), diff --git a/lib/pages/bells_page.dart b/lib/pages/bells_page.dart index a84e6c6..b6567fc 100644 --- a/lib/pages/bells_page.dart +++ b/lib/pages/bells_page.dart @@ -23,6 +23,7 @@ class _BellPageState extends State { bool _enableBG = true; bool _changingOrder = false; + /// updates the [Bell]s with new database data Future _updateBells() async { List> bellsData = await _dbHandler.getBells(); List newBells = []; @@ -39,6 +40,7 @@ class _BellPageState extends State { }); } + /// moves a [Bell] from an [oldPosition] to a [newPosition] void _moveBell(int oldPosition, int newPosition) { setState(() { if (oldPosition < newPosition) { @@ -56,6 +58,8 @@ class _BellPageState extends State { _refresh(); } + /// refreshes the [BellPage] + /// - @param [settingsOnly] - set [true] to this if you only wanna update settings changes by default its [false] void _refresh({bool settingsOnly = false}) { _settings.getBGEnabled.then((value) { setState(() { @@ -107,7 +111,7 @@ class _BellPageState extends State { MaterialPageRoute( builder: (context) => const SettingsPage(), ), - ).then((value) => _refresh(settingsOnly: true)); + ).then((_) => _refresh(settingsOnly: true)); }, child: const Icon(Icons.settings), style: ButtonStyle( @@ -124,38 +128,32 @@ class _BellPageState extends State { floatingActionButton: FloatingActionButton( backgroundColor: const Color(0xff53a679), tooltip: "add new bell", - onPressed: () { - Navigator.push( + onPressed: () async { + // adds a new bell + Bell? newBell = await Navigator.push( context, MaterialPageRoute( builder: (context) => const AddNewBellPage(), ), - ).then((bell) { - if (bell != null) { - bell.position = bells.length; - _dbHandler.insertBell(bell).then((bellId) { - setState(() { - _updateBells(); - }); - Navigator.push( - context, - MaterialPageRoute( - builder: (context) => BellEditingPage( - bell: bell..id = bellId, - ), - ), - ).then((value) { - if (value != null) { - _dbHandler.updateBell(value).then((value) { - setState(() { - _updateBells(); - }); - }); - } - }); - }); + ); + if (newBell != null) { + newBell.position = bells.length; + // inserting the new bell to the DataBase + int bellId = await _dbHandler.insertBell(newBell); + _updateBells(); + Bell? editedBell = await Navigator.push( + context, + MaterialPageRoute( + builder: (context) => BellEditingPage( + bell: newBell..id = bellId, + ), + ), + ); + if (editedBell != null) { + await _dbHandler.updateBell(editedBell); + _updateBells(); } - }); + } }, child: const Icon(Icons.add_alert), ), @@ -248,12 +246,9 @@ class _BellPageState extends State { .withOpacity(0.1)), ), child: const Text("Delete"), - onPressed: () { - _dbHandler - .deleteBell(bell) - .then((value) { - _updateBells(); - }); + onPressed: () async { + await _dbHandler.deleteBell(bell); + await _updateBells(); Navigator.pop(context); }, ), @@ -300,23 +295,19 @@ class _BellPageState extends State { force: true, disableTimer: true); } }, - onTap: (Bell bell) { - Navigator.push( + onTap: (Bell bell) async { + Bell? editedBell = await Navigator.push( context, MaterialPageRoute( builder: (context) => BellEditingPage( bell: bell, ), ), - ).then((value) { - if (value != null) { - _dbHandler.updateBell(value).then((value) { - setState(() { - _updateBells(); - }); - }); - } - }); + ); + if (editedBell != null) { + await _dbHandler.updateBell(editedBell); + await _updateBells(); + } }, ), ), diff --git a/lib/pages/settings_page.dart b/lib/pages/settings_page.dart index 67cfff9..4856750 100644 --- a/lib/pages/settings_page.dart +++ b/lib/pages/settings_page.dart @@ -127,9 +127,17 @@ class ApplicationSettingsPage extends StatefulWidget { class _ApplicationSettingsPageState extends State { final Settings _settings = Settings.instance; + + /// launch on system startup late bool _launchOnStartup; + + /// preventing close late bool _preventClose; + + /// showing notifications late bool _showNotifications; + + /// show back ground image late bool _showBG; @override diff --git a/lib/settings.dart b/lib/settings.dart index 0bd52c4..c73879a 100644 --- a/lib/settings.dart +++ b/lib/settings.dart @@ -2,23 +2,30 @@ import 'package:launch_at_startup/launch_at_startup.dart'; import 'package:shared_preferences/shared_preferences.dart'; import 'package:window_manager/window_manager.dart'; +/// [Settings] manager class Settings { Settings._init(); + + /// [Settings] instance static final Settings instance = Settings._init(); static SharedPreferences? _prefs; Future get prefs async => _prefs ??= await SharedPreferences.getInstance(); + /// launch on system startup Future get getLaunchOnStartup async => (await prefs).getBool('launchOnStartup'); + /// prevents from closing the window Future get getPreventClose async => (await prefs).getBool('preventClose'); + /// show notifications Future get getShowNotifications async => (await prefs).getBool('showNotifications'); + /// icmu background image enabled or not Future get getBGEnabled async { SharedPreferences _sharedPrefs = await prefs; bool? bgEnabled = _sharedPrefs.getBool('BGEnabled'); @@ -29,23 +36,27 @@ class Settings { return bgEnabled; } + /// enable or disable icmu background image Future setBGEnabled(bool value) async { SharedPreferences sharedPrefs = await prefs; sharedPrefs.setBool('BGEnabled', value); } + /// enable or disable launching on system startup Future setLaunchOnStartup(bool value) async { SharedPreferences sharedPrefs = await prefs; value ? launchAtStartup.enable() : launchAtStartup.disable(); sharedPrefs.setBool('launchOnStartup', value); } + /// enable or disable preventing from closing the window Future setPreventClose(bool value) async { SharedPreferences sharedPrefs = await prefs; windowManager.setPreventClose(value); await sharedPrefs.setBool('preventClose', value); } + /// enable or disable notification Future setShowNotifications(bool value) async { SharedPreferences sharedPrefs = await prefs; sharedPrefs.setBool('showNotifications', value); diff --git a/lib/widgets/bell_card.dart b/lib/widgets/bell_card.dart index cecdee9..0d25641 100644 --- a/lib/widgets/bell_card.dart +++ b/lib/widgets/bell_card.dart @@ -55,6 +55,7 @@ class _BellCardState extends State { checkForErrors(); } + /// checking for [BellErrors] Future checkForErrors() async { bool activateable = await widget.bell.activateable; if (activateable == false) { @@ -230,11 +231,21 @@ class _BellCardState extends State { } } -/// a widget that animates the border of the timer to blink in order to indicate that the bell timer has been activated +/// a [Widget] that animates the border of the timer to blink in order to indicate that the bell timer has been activated +/// or to indicate that there are [BellErrors] class TimerActiveIndicator extends StatefulWidget { + /// is timer activated final bool timerActivated; + + /// can bell activated final bool activateable; + + /// [DateTime] of the time which bell is gonna ring at final DateTime dateTime; + + /// [BellErrors] if there is any [BellErrors] + /// - it will change the [TimerActiveIndicator] [Color] to `Color(0xff53a679)` (red) + /// - and it will let the user tap on it and see what are the [BellErrors] final BellErrors? bellErrors; const TimerActiveIndicator({ Key? key, @@ -273,6 +284,7 @@ class _TimerActiveIndicatorState extends State if (widget.activateable || (widget.bellErrors == null || !widget.bellErrors!.isThereErrors)) { + // where there are no Bell Errors return Tooltip( message: widget.timerActivated ? 'timer activated' : 'timer is not active', @@ -321,6 +333,7 @@ class _TimerActiveIndicatorState extends State ), ); } else { + // whern there are bell errors return Tooltip( message: 'there are errors click to see them', child: InkWell( @@ -385,9 +398,9 @@ class _TimerActiveIndicatorState extends State } } -/// this will shake the child component -/// designed to indicate that the child widget is draggable -/// like in the IOS apps start to shake when dragging +/// this will shake the child [Widget] +/// designed to indicate that the child [Widget] is draggable +/// like in the IOS, apps starts to shake when dragging class ShakeWidget extends StatefulWidget { final Widget child; final bool shake; @@ -421,6 +434,8 @@ class _ShakeWidgetState extends State @override Widget build(BuildContext context) { + /// picking a random point to start the animation + /// so bellCards wont shake at the same time int random(min, max) { return min + Random().nextInt(max - min); } diff --git a/lib/widgets/select_days.dart b/lib/widgets/select_days.dart index 7edfda7..16ea44f 100644 --- a/lib/widgets/select_days.dart +++ b/lib/widgets/select_days.dart @@ -1,5 +1,6 @@ import 'package:flutter/material.dart'; +/// week days picker class SelectDays extends StatefulWidget { final List days; final Function()? onChange; diff --git a/lib/widgets/title_bar.dart b/lib/widgets/title_bar.dart index 3306c86..24ebce5 100644 --- a/lib/widgets/title_bar.dart +++ b/lib/widgets/title_bar.dart @@ -2,16 +2,45 @@ import 'package:bitsdojo_window/bitsdojo_window.dart'; import 'package:flutter/material.dart'; import 'package:window_manager/window_manager.dart'; +/// titleBar of the application this contains the `close`,`minimize` and `resize` buttons and +/// also this has ability to drag the window class TitleBar extends StatelessWidget implements PreferredSizeWidget { + /// [title] of the [TitleBar] final String? title; + + /// background [Color] final Color? backgroundColor; + + /// [Color] of the close button final Color? closeButtonColor; + + /// text [Color] final Color? textColor; + + /// color of the buttons final Color? buttonColor; + + /// background [Color] around the three buttons (`close`,`minimize` and `resize`) final Color? windowButtonBGColor; + + /// style of the close button (`x` button) final ButtonStyle? closeButtonStyle; + + /// you can add widget before the three buttons with this [suffixTools] final Widget? suffixTools; + + /// widget that is below the title bar + /// like a navigation bar or something + /// you can add any [Widget] to here final Widget? bottom; + + /// size of the [TitleBar] + /// its better if you use [Height] + /// + /// by default its + /// ```dart + /// const Size.fromHeight(28) + /// ``` final Size customPrefferedSize; const TitleBar( {Key? key, @@ -103,9 +132,19 @@ class TitleBar extends StatelessWidget implements PreferredSizeWidget { } class WindowButtons extends StatelessWidget { + /// color of the buttons final Color? buttonColor; + + /// color of the close button final Color? closeButtonColor; + + /// background color final Color? backgroundColor; + + /// #### close button style + /// if the [closeButtonStyle] is not [null] + /// + /// then it will ignore the [closeButtonColor] final ButtonStyle? closeButtonStyle; const WindowButtons( {Key? key,