Add DartDoc comments, remove useless code, and change variable names

GanZhiXiong · Apr 6, 2021 · c5a9b4f · c5a9b4f
1 parent 1e9ea8d
commit c5a9b4f
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 9 deletions.
diff --git a/example/lib/gzx_dropdown_menu_test_page.dart b/example/lib/gzx_dropdown_menu_test_page.dart
@@ -83,6 +83,7 @@ class _GZXDropDownMenuTestPageState extends State<GZXDropDownMenuTestPage> {
           children: <Widget>[TextField()],
         ),
       ),
+      // GZXDropDownMenu只能在Stack内，后续有时间会改进，以及支持CustomScrollView和NestedScrollView
       body: Stack(
         key: _stackKey,
         children: <Widget>[
@@ -163,7 +164,7 @@ class _GZXDropDownMenuTestPageState extends State<GZXDropDownMenuTestPage> {
               ),
             ],
           ),
-          // 下拉菜单
+          // 下拉菜单，注意GZXDropDownMenu只能在Stack内
           GZXDropDownMenu(
             // controller用于控制menu的显示或隐藏
             controller: _dropdownMenuController,
@@ -197,7 +198,8 @@ class _GZXDropDownMenuTestPageState extends State<GZXDropDownMenuTestPage> {
                   dropDownHeight: 40 * 8.0,
                   dropDownWidget: _buildConditionListWidget(_brandSortConditions, (value) {
                     _selectBrandSortCondition = value;
-                    _dropDownHeaderItemStrings[1] = _selectBrandSortCondition.name == '全部' ? '品牌' : _selectBrandSortCondition.name;
+                    _dropDownHeaderItemStrings[1] =
+                        _selectBrandSortCondition.name == '全部' ? '品牌' : _selectBrandSortCondition.name;
                     _dropdownMenuController.hide();
                     setState(() {});
                   })),

diff --git a/lib/src/gzx_dropdown_header.dart b/lib/src/gzx_dropdown_header.dart
@@ -1,8 +1,10 @@
 import 'package:flutter/material.dart';
 import 'gzx_dropdown_menu_controller.dart';
 
+/// Signature for when a tap has occurred.
 typedef OnItemTap<T> = void Function(T value);
 
+/// Dropdown header widget.
 class GZXDropDownHeader extends StatefulWidget {
   final Color color;
   final double borderWidth;
@@ -22,6 +24,7 @@ class GZXDropDownHeader extends StatefulWidget {
   final List<GZXDropDownHeaderItem> items;
   final GlobalKey stackKey;
 
+  /// Creates a dropdown header widget, Contains more than one header items.
   GZXDropDownHeader({
     Key? key,
     required this.items,
@@ -118,7 +121,7 @@ class _GZXDropDownHeaderState extends State<GZXDropDownHeader> with SingleTicker
         var size = dropDownItemRenderBox.size;
 //        print("SIZE : $size");
 
-        widget.controller.dropDownHeaderHeight = size.height + position.dy;
+        widget.controller.dropDownMenuTop = size.height + position.dy;
 
         if (index == menuIndex) {
           if (widget.controller.isShow) {

diff --git a/lib/src/gzx_dropdown_menu.dart b/lib/src/gzx_dropdown_menu.dart
@@ -2,23 +2,34 @@ import 'package:flutter/material.dart';
 
 import 'gzx_dropdown_menu_controller.dart';
 
+/// Information about the dropdown menu widget, such as the height of the drop down menu to be displayed.
 class GZXDropdownMenuBuilder {
+  /// A dropdown menu displays the widget.
   final Widget dropDownWidget;
+
+  /// Dropdown menu height.
   final double dropDownHeight;
 
   GZXDropdownMenuBuilder({required this.dropDownWidget, required this.dropDownHeight});
 }
 
 typedef DropdownMenuChange = void Function(bool isShow, int? index);
 
+/// Dropdown menu widget.
 class GZXDropDownMenu extends StatefulWidget {
   final GZXDropdownMenuController controller;
   final List<GZXDropdownMenuBuilder> menus;
   final int animationMilliseconds;
   final Color maskColor;
+
+  /// Called when dropdown menu start showing or hiding.
   final DropdownMenuChange? dropdownMenuChanging;
+
+  /// Called when dropdown menu has been shown or hidden.
   final DropdownMenuChange? dropdownMenuChanged;
 
+  /// Creates a dropdown menu widget.
+  /// The widget must be inside the Stack because the widget is a Positioned.
   const GZXDropDownMenu(
       {Key? key,
       required this.controller,
@@ -173,7 +184,7 @@ class _GZXDropDownMenuState extends State<GZXDropDownMenu> with SingleTickerProv
 
     return Positioned(
         width: MediaQuery.of(context).size.width,
-        top: widget.controller.dropDownHeaderHeight,
+        top: widget.controller.dropDownMenuTop,
         left: 0,
         child: Column(
           children: <Widget>[

diff --git a/lib/src/gzx_dropdown_menu_controller.dart b/lib/src/gzx_dropdown_menu_controller.dart
@@ -1,24 +1,31 @@
 import 'package:flutter/foundation.dart';
 
-enum DropDownType { current, another }
-
+/// GZXDropdownMenuController use to show and hide drop-down menus.
+/// Used for GZXDropdownHeader and GZXDropdownMenu passing[dropDownMenuTop], [menuIndex], [isShow] and [isShowHideAnimation].
 class GZXDropdownMenuController extends ChangeNotifier {
-  double? dropDownHeaderHeight;
+  /// [dropDownMenuTop] that the GZXDropDownMenu top edge is inset from the top of the stack.
+  ///
+  /// Since the GZXDropDownMenu actually returns a Positioned widget, the GZXDropDownMenu must be inside the Stack
+  /// vertically.
+  double? dropDownMenuTop;
 
+  /// Current or last dropdown menu index, default is 0.
   int menuIndex = 0;
 
+  /// Whether to display a dropdown menu.
   bool isShow = false;
 
+  /// Whether to display animations when hiding dropdown menu.
   bool isShowHideAnimation = false;
 
-  DropDownType? dropDownType;
-
+  /// Use to display GZXDropdownMenu specified dropdown menu index.
   void show(int index) {
     isShow = true;
     menuIndex = index;
     notifyListeners();
   }
 
+  /// Use to hide GZXDropdownMenu. If you don't need to show the hidden animation, [isShowHideAnimation] pass in false, Like when you click on another GZXDropdownHeaderItem.
   void hide({bool isShowHideAnimation = true}) {
     this.isShowHideAnimation = isShowHideAnimation;
     isShow = false;