CNPopupMenuButton class

A Cupertino-native popup menu button.

On iOS/macOS this embeds a native popup button and shows a native menu.

Inheritance
Available extensions

Constructors

CNPopupMenuButton({Key? key, required String? buttonLabel, required List<CNPopupMenuEntry> items, ValueChanged<int>? onSelected, ValueChanged<List<int>>? onPathSelected, Color? tint, double height = 32.0, bool shrinkWrap = false, CNButtonStyle buttonStyle = CNButtonStyle.plain, bool preserveTopToBottomOrder = false, bool autoHideOnModal = true, String? semanticLabel, CNSymbol? buttonIcon, IconData? buttonCustomIcon, Color? buttonCustomIconColor, CNImageAsset? buttonImageAsset, CNImagePlacement imagePlacement = CNImagePlacement.leading, double? imagePadding, String? labelFontFamily, double? labelFontSize, FontWeight? labelFontWeight, Color? labelColor, Color? labelColorLight, Color? labelColorDark, bool keepsSourceVisible = false, VoidCallback? onOpened, VoidCallback? onClosed})
Creates a text-labeled popup menu button.
const
CNPopupMenuButton.icon({Key? key, CNSymbol? buttonIcon, IconData? buttonCustomIcon, Color? buttonCustomIconColor, CNImageAsset? buttonImageAsset, required List<CNPopupMenuEntry> items, ValueChanged<int>? onSelected, ValueChanged<List<int>>? onPathSelected, Color? tint, double size = 44.0, CNButtonStyle buttonStyle = CNButtonStyle.glass, bool preserveTopToBottomOrder = false, bool autoHideOnModal = true, String? semanticLabel, bool keepsSourceVisible = false, VoidCallback? onOpened, VoidCallback? onClosed})
Creates a round, icon-only popup menu button.

Properties

autoHideOnModal → bool
When true (default), destroys the native popup menu's PlatformView while a modal sheet is presented above this widget's host route. Fixes the iOS hybrid-composition z-order bleed (Issue #53) where a host-page CN-widget's pixels leak through a sheet that also contains a CN-widget. Requires CNTabBarRouteObserver() to be registered in the app's navigatorObservers. No effect on iOS < 26 / non-iOS (Flutter fallback).
final
buttonCustomIcon → IconData?
Optional custom icon from CupertinoIcons, Icons, or any IconData for the button. If provided, this takes precedence over buttonIcon but not buttonImageAsset.
final
buttonCustomIconColor → Color?
Optional color for the buttonCustomIcon.
final
buttonIcon → CNSymbol?
Icon for the button: the round button's icon, or shown next to buttonLabel. Priority: buttonImageAsset > buttonCustomIcon > buttonIcon
final
buttonImageAsset → CNImageAsset?
Optional image asset (SVG, PNG, etc.) for the button icon. If provided, this takes precedence over buttonIcon and buttonCustomIcon.
final
buttonLabel → String?
Text for the button (null for the round icon button).
final
buttonStyle → CNButtonStyle
Visual style to apply to the button.
final
hashCode → int
The hash code for this object.
no setterinherited
height → double
Control height; icon mode uses diameter semantics.
final
imagePadding → double?
The gap between the icon and buttonLabel, in points. Null keeps the system's.
final
imagePlacement → CNImagePlacement
Where the icon goes relative to buttonLabel when the button has both (iOS 15+; on macOS the button's image position).
final
isIconButton → bool
Whether this is the round, icon-only variant (CNPopupMenuButton.icon).
no setter
items → List<CNPopupMenuEntry>
Entries that populate the popup menu.
final
keepsSourceVisible → bool
iOS 26+: whether the button is left out of the menu's morph.
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
labelColor → Color?
The colour of buttonLabel. Null keeps the button style's. The same colour is used on light and on dark glass; use labelColorLight and labelColorDark for one colour each.
final
labelColorDark → Color?
The colour of buttonLabel while the button has a dark appearance: on glass that is dark (over dark content), or in dark mode for the other styles. Without this, the dark side uses labelColor, else the style's colour.
final
labelColorLight → Color?
The colour of buttonLabel while the button has a light appearance: on glass that is light (over light content), or in light mode for the other styles. Liquid Glass picks its appearance from what is behind it, and the label switches with it, as the default label does; on macOS it keeps the window's appearance, so the pair follows light and dark mode. Without this, the light side uses labelColor, else the style's colour.
final
labelFontFamily → String?
The font family of buttonLabel, e.g. a font declared under fonts: in pubspec.yaml, which the package registers with the system the first time it is used. Null keeps the system font. The menu's own item titles always use the system font: a native menu has no font setting.
final
labelFontSize → double?
The size of buttonLabel, in points. Null keeps the system's.
final
labelFontWeight → FontWeight?
The weight of buttonLabel, also applied with labelFontFamily (the family's nearest face).
final
onClosed → VoidCallback?
Called each time the menu has closed, whether or not an item was chosen. A choice is reported to onSelected / onPathSelected as well, around the same moment.
final
onOpened → VoidCallback?
Called each time the menu is about to show, as PopupMenuButton.onOpened is.
final
onPathSelected → ValueChanged<List<int>>?
Called with the path to the selected item, for every selection.
final
onSelected → ValueChanged<int>?
Called with the index in items of the selected entry, dividers included.
final
preserveTopToBottomOrder → bool
When true, items maintain top-to-bottom order even when menu opens upward.
final
round → bool
Whether this is the round icon variant.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
semanticLabel → String?
What VoiceOver reads for the button.
final
shrinkWrap → bool
If true, sizes the control to its intrinsic width.
final
tint → Color?
Tint color for the control.
final
width → double?
Fixed width in icon mode; otherwise computed/intrinsic.
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<CNPopupMenuButton>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
liquidGlass({CNGlassEffect effect = CNGlassEffect.regular, CNGlassEffectShape shape = CNGlassEffectShape.capsule, double? cornerRadius, Color? tint, bool interactive = false}) → Widget

Available on Widget, provided by the LiquidGlassExtension extension

Applies a Liquid Glass effect to this widget.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited