Refactor icon handling and improve docstrings

Updated icon construction logic in navigation bar controls to use buildIconOrWidget for consistency. Improved and clarified docstrings for Icon and NavigationBarDestination classes in Python, including parameter explanations and accessibility notes. Refactored theme parsing for switch themes to simplify argument usage. Minor formatting and doc improvements in CupertinoNavigationBar and IconData.

Author: FeodorFitsner

packages/flet/lib/src/controls/cupertino_navigation_bar.dart

@@ -5,7 +5,6 @@ import '../extensions/control.dart';
 import '../models/control.dart';
 import '../utils/borders.dart';
 import '../utils/colors.dart';
-import '../utils/icons.dart';
 import '../utils/numbers.dart';
 import '../widgets/flet_store_mixin.dart';
 import 'base_controls.dart';
@@ -55,7 +54,7 @@ class _CupertinoNavigationBarControlState
           return BottomNavigationBarItem(
               tooltip: !dest.disabled ? dest.getString("tooltip") : null,
               backgroundColor: dest.getColor("bgcolor", context),
-              icon: dest.buildWidget("icon") ?? Icon(dest.getIconData("icon")),
+              icon: dest.buildIconOrWidget("icon")!,
               activeIcon: dest.buildIconOrWidget("selected_icon"),
               label: dest.getString("label", "")!);
         }).toList());

packages/flet/lib/src/controls/navigation_bar_destination.dart

@@ -19,7 +19,7 @@ class NavigationBarDestinationControl extends StatelessWidget {
     var child = NavigationDestination(
         enabled: !control.disabled,
         tooltip: !control.disabled ? control.getString("tooltip") : null,
-        icon: control.buildWidget("icon") ?? Icon(control.getIconData("icon")),
+        icon: control.buildIconOrWidget("icon")!,
         selectedIcon: control.buildWidget("selected_icon") ??
             (selectedIcon != null ? Icon(selectedIcon) : null),
         label: control.getString("label", "")!);

packages/flet/lib/src/utils/icons.dart

@@ -15,7 +15,7 @@ IconData? parseIconData(int? value, FletBackend backend,
     }
   }
 
-  return null;
+  return defaultValue;
 }
 
 WidgetStateProperty<Icon?>? parseWidgetStateIcon(

packages/flet/lib/src/utils/theme.dart

@@ -160,7 +160,7 @@ ThemeData parseTheme(
     checkboxTheme: parseCheckboxTheme(value?["checkbox_theme"], theme),
     radioTheme: parseRadioTheme(value?["radio_theme"], theme),
     badgeTheme: parseBadgeTheme(value?["badge_theme"], theme),
-    switchTheme: parseSwitchTheme(value?["switch_theme"], theme, context),
+    switchTheme: parseSwitchTheme(value?["switch_theme"], context),
     dividerTheme: parseDividerTheme(value?["divider_theme"], theme),
     snackBarTheme: parseSnackBarTheme(value?["snackbar_theme"], theme),
     bannerTheme: parseBannerTheme(value?["banner_theme"], theme),
@@ -661,10 +661,10 @@ BadgeThemeData? parseBadgeTheme(Map<dynamic, dynamic>? value, ThemeData theme,
 }
 
 SwitchThemeData? parseSwitchTheme(
-    Map<dynamic, dynamic>? value, ThemeData theme, BuildContext context,
+    Map<dynamic, dynamic>? value, BuildContext context,
     [SwitchThemeData? defaultValue]) {
   if (value == null) return defaultValue;
-
+  var theme = Theme.of(context);
   return theme.switchTheme.copyWith(
     thumbColor: parseWidgetStateColor(value["thumb_color"], theme),
     trackColor: parseWidgetStateColor(value["track_color"], theme),
@@ -1392,10 +1392,9 @@ extension ThemeParsers on Control {
     return parseBadgeTheme(get(propertyName), theme, defaultValue);
   }
 
-  SwitchThemeData? getSwitchTheme(
-      String propertyName, ThemeData theme, BuildContext context,
+  SwitchThemeData? getSwitchTheme(String propertyName, BuildContext context,
       [SwitchThemeData? defaultValue]) {
-    return parseSwitchTheme(get(propertyName), theme, context, defaultValue);
+    return parseSwitchTheme(get(propertyName), context, defaultValue);
   }
 
   DividerThemeData? getDividerTheme(String propertyName, ThemeData theme,

sdk/python/packages/flet/src/flet/controls/core/icon.py

@@ -11,7 +11,10 @@
 @control("Icon")
 class Icon(ConstrainedControl):
     """
-    Displays a Material icon.
+    A control that displays an icon from a built-in or custom icon set.
+
+    Icons can be customized in color, size, and visual style using various
+    parameters such as stroke weight, fill level, and shadows.
 
     Raises:
         AssertionError: If [`fill`][(c).] is less than `0.0` or greater than `1.0`.
@@ -21,111 +24,88 @@ class Icon(ConstrainedControl):
 
     icon: IconData
     """
-    The icon to display.
+    The icon to display, selected from a predefined icon set.
 
-    You can search through the list of all available icons using our
-    [Icons browser](https://gallery.flet.dev/icons-browser/) app
-    [written in Flet](https://github.com/flet-dev/examples/blob/main/python/apps/icons-browser/main.py).
+    You can explore available icons using the
+    [Flet Icons Browser](https://gallery.flet.dev/icons-browser/).
     """
 
     color: Optional[ColorValue] = None
     """
-    Icon color.
+    The color to use when drawing the icon.
     """
 
     size: Optional[Number] = None
     """
-    The icon's size.
-
-    Icons occupy a square with width and height equal to `size`.
-
-    Defaults to the nearest [`IconTheme.size`][flet.IconTheme.size].
+    The size (width and height) of the square area the icon will occupy.
 
-    If this `Icon` is being placed inside an [`IconButton`][flet.IconButton], then use
-    [`IconButton.icon_size`][flet.IconButton.icon_size] instead, so that the
-    `IconButton` can make the splash area the appropriate size as well.
-    The `IconButton` uses an [`IconTheme`][flet.IconTheme] to pass down the
-    size to the `Icon`.
+    If not set, a default size will be used. When placing this icon
+    inside other controls (such as buttons), those controls may also affect sizing.
     """
 
     semantics_label: Optional[str] = None
     """
-    The semantics label for this icon.
+    An accessibility label for the icon.
 
-    It is not shown to the in the UI, but is announced in accessibility modes
-    (e.g. TalkBack/VoiceOver).
+    This text is not displayed visually but may be announced by screen readers
+    or other assistive technologies.
     """
 
     shadows: Optional[BoxShadowValue] = None
     """
-    A list of Shadows that will be painted underneath the icon.
+    A list of shadows to apply beneath the icon.
 
-    Multiple shadows are supported to replicate lighting from multiple light sources.
-
-    Shadows must be in the same order for Icon to be considered as equivalent as order
-    produces differing transparency.
+    Use multiple shadows to simulate complex lighting effects.
+    The order of shadows matters for how transparency is blended.
     """
 
     fill: Optional[Number] = None
     """
-    The fill for drawing the icon.
-
-    Requires the underlying icon font to support the `FILL` FontVariation axis,
-    otherwise has no effect. Variable font filenames often indicate the supported axes.
-    Must be between `0.0` (unfilled) and `1.0` (filled), inclusive.
+    The fill amount of the icon, between `0.0` (outline) and `1.0` (solid).
 
-    Can be used to convey a state transition for animation or interaction.
+    This feature requires the icon's font to support fill variation.
+    It can be used to indicate state transitions or selection visually.
     """
 
     apply_text_scaling: Optional[bool] = None
     """
-    Whether to scale the size of this widget using the ambient MediaQuery's TextScaler.
+    Whether to scale the icon based on the system or user's preferred text size.
 
-    This is specially useful when you have an icon associated with a text,
-    as scaling the text without scaling the icon would result in a confusing interface.
+    Useful when placing icons alongside text, ensuring both scale consistently
+    for better readability and accessibility.
     """
 
     grade: Optional[Number] = None
     """
-    The grade (granular stroke weight) for drawing the icon.
+    A fine-tuning adjustment for the stroke thickness of the icon.
 
-    Requires the underlying icon font to support the `GRAD` FontVariation axis,
-    otherwise has no effect. Variable font filenames often indicate the supported axes.
-    Can be negative.
-
-    Grade and weight both affect a symbol's stroke weight (thickness),
-    but grade has a smaller impact on the size of the symbol.
-
-    Grade is also available in some text fonts. One can match grade levels between
-    text and symbols for a harmonious visual effect. For example, if the text font
-    has a -25 grade value, the symbols can match it with a suitable value, say -25.
+    This requires support from the icon's font. Grade values can be negative or
+    positive.
+    It allows precise visual adjustments without changing icon size.
     """
 
     weight: Optional[Number] = None
     """
-    The stroke weight for drawing the icon.
+    The stroke weight (thickness) of the icon's lines.
 
-    Requires the underlying icon font to support the `wght` FontVariation axis,
-    otherwise has no effect. Variable font filenames often indicate the supported axes.
+    This requires the icon font to support weight variation.
     Must be greater than `0`.
     """
 
     optical_size: Optional[Number] = None
     """
-    The optical size for drawing the icon.
+    Adjusts the icon's visual style for different sizes to maintain clarity and balance.
 
-    Requires the underlying icon font to support the `opsz` FontVariation axis,
-    otherwise has no effect. Variable font filenames often indicate the supported axes.
+    This requires the icon font to support optical sizing.
     Must be greater than `0`.
-
-    For an icon to look the same at different sizes, the stroke weight (thickness)
-    must change as the icon size scales. Optical size offers a way to automatically
-    adjust the stroke weight as icon size changes.
     """
 
     blend_mode: Optional[BlendMode] = BlendMode.SRC_OVER
     """
-    The BlendMode to apply to the foreground of the icon.
+    The blend mode used when rendering the icon.
+
+    Blend modes control how the icon's color interacts with the background.
+    The default is normal blending (`SRC_OVER`).
     """
 
     def before_update(self):

sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_navigation_bar.py

@@ -23,7 +23,8 @@ class CupertinoNavigationBar(ConstrainedControl):
     destinations in an app.
 
     Raises:
-        AssertionError: If [`destinations`][(c).] does not contain at least two visible [`NavigationBarDestination`][flet.NavigationBarDestination]s.
+        AssertionError: If [`destinations`][(c).] does not contain at least two visible
+        [`NavigationBarDestination`][flet.NavigationBarDestination]s.
         IndexError: If [`selected_index`][(c).] is out of range.
     """
 
@@ -33,15 +34,15 @@ class CupertinoNavigationBar(ConstrainedControl):
 
     Note:
         Must be a list of two or more [`NavigationBarDestination`][flet.NavigationBarDestination]s.
-    """
+    """  # noqa: E501
 
     selected_index: int = 0
     """
-    The index into [`destinations`][flet.CupertinoNavigationBar.destinations] for the currently
-    selected [`NavigationBarDestination`][flet.NavigationBarDestination].
+    The index into [`destinations`][flet.CupertinoNavigationBar.destinations] for the
+    currently selected [`NavigationBarDestination`][flet.NavigationBarDestination].
 
     Note:
-        Must be a value between `0` and the length of visible 
+        Must be a value between `0` and the length of visible
         [`destinations`][flet.CupertinoNavigationBar.destinations], inclusive.
     """
 
@@ -87,5 +88,6 @@ def before_update(self):
         if not (0 <= self.selected_index < visible_destinations_count):
             raise IndexError(
                 f"selected_index ({self.selected_index}) is out of range. "
-                f"Expected a value between 0 and {visible_destinations_count - 1} inclusive."
+                f"Expected a value between 0 and {visible_destinations_count - 1} "
+                "inclusive."
             )

sdk/python/packages/flet/src/flet/controls/icon_data.py

@@ -31,12 +31,28 @@ class IconData(IntEnum):
     """
 
     def __new__(cls, value):
+        """
+        Create a new IconData enum member.
+
+        Args:
+            value: The encoded integer representing the icon.
+
+        Returns:
+            An instance of the enum with the encoded value.
+        """
         obj = int.__new__(cls, value)
         obj._value_ = value
         return obj
 
     @classmethod
     def __init_subclass__(cls, **kwargs):
+        """
+        Hook called when a subclass is defined. Used to attach metadata.
+
+        Keyword Args:
+            package_name: The Flutter package where the icon set is defined.
+            class_name: The name of Flutter class with icon definitions.
+        """
         cls._package_name = kwargs.pop("package_name", "")
         cls._class_name = kwargs.pop("class_name", "")
         super().__init_subclass__(**kwargs)

sdk/python/packages/flet/src/flet/controls/material/navigation_bar.py

@@ -39,12 +39,7 @@ class NavigationBarDestination(AdaptiveControl):
     The value must be a list of two or more NavigationBarDestination instances.
     """
 
-    label: Optional[str] = None
-    """
-    The text label that appears below the icon of this `NavigationBarDestination`.
-    """
-
-    icon: Optional[IconDataOrControl] = None
+    icon: IconDataOrControl
     """
     The [name of the icon](https://flet.dev/docs/reference/icons) or `Control` of the
     destination.
@@ -66,6 +61,11 @@ class NavigationBarDestination(AdaptiveControl):
     should be set to the stroked version and `selected_icon` to the filled version.
     """
 
+    label: Optional[str] = None
+    """
+    The text label that appears below the icon of this `NavigationBarDestination`.
+    """
+
     selected_icon: Optional[IconDataOrControl] = None
     """
     The [name](https://flet.dev/docs/reference/icons) of alternative icon or `Control`