MacosPopupButton (closes #176)

CHANGELOG.md

@@ -1,3 +1,6 @@
+## [0.11.0]
+* New Widget: `MacosPopupButton`
+
 ## [0.10.1]
 * Added support for transparent sidebar. Please note that changes to `MainFlutterWindow.swift` are required for this to work. [(#175)](https://github.com/GroovinChip/macos_ui/pull/175)
 

README.md

@@ -236,6 +236,46 @@ MacosRadioButton(
 ),
 ```
 
+## Pop-Up Button
+
+A pop-up button (often referred to as a pop-up menu) is a type of button that, when clicked, displays a menu containing a list of mutually exclusive choices. The menu appears on top of the button. Like other types of menus, a pop-up button’s menu can include separators and symbols like checkmarks. After the menu is revealed, it remains open until the user chooses a menu item, clicks outside of the menu, switches to another app, or quits the app; or until the system displays an alert. [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/buttons/pop-up-buttons/)
+
+The type `T` of the `MacosPopupButton` is the type of the value that each pop-up menu item represents. All the entries in a given menu must represent values with consistent types. Typically, an `enum` is used. Each `MacosPopupMenuItem` in items must be specialized with that same type argument.
+
+The `onChanged` callback should update a state variable that defines the pop-up menu's value. It should also call `State.setState` to rebuild the pop-up button with the new value.
+
+When there are menu items that cannot be displayed within the available menu constraints, a caret is shown at the top or bottom of the open menu to signal that there are items that are not currently visible. 
+
+The menu can also be navigated with the up/down keys and an item selected with the Return key.
+
+| Dark Theme                                 | Light Theme                                |
+| ------------------------------------------ | ------------------------------------------ |
+| <img src="https://imgur.com/ov0kzJC.jpg"/> | <img src="https://imgur.com/buhYEo1.jpg"/> |
+| <img src="https://imgur.com/BOEH59L.jpg"/> | <img src="https://imgur.com/61S7DSX.jpg"/> |
+| <img src="https://imgur.com/zY0d8RF.jpg"/> | <img src="https://imgur.com/W4CMa5z.jpg"/> |
+
+Here's an example of how to create a basic pop-up button:
+
+```dart
+String popupValue = 'One';
+
+MacosPopupButton<String>(
+  value: popupValue,
+  onChanged: (String? newValue) {
+    setState(() {
+      popupValue = newValue!;
+    });
+  },
+  items: <String>['One', 'Two', 'Three', 'Four']
+      .map<MacosPopupMenuItem<String>>((String value) {
+    return MacosPopupMenuItem<String>(
+      value: value,
+      child: Text(value),
+    );
+  }).toList(),
+),
+```
+
 ## PushButton
 
 A push button appears within a view and initiates an instantaneous app-specific action, such as printing a document or deleting a file. Push buttons contain text—not icons—and often open a separate window, dialog, or app so the user can complete a task. [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/buttons/push-buttons/)

example/lib/pages/buttons.dart

@@ -13,6 +13,9 @@ class ButtonsPage extends StatefulWidget {
 }
 
 class _ButtonsPageState extends State<ButtonsPage> {
+  String popupValue = 'One';
+  String languagePopupValue = 'English';
+
   @override
   Widget build(BuildContext context) {
     return MacosScaffold(
@@ -164,6 +167,42 @@ class _ButtonsPageState extends State<ButtonsPage> {
                   },
                 ),
                 const SizedBox(height: 20),
+                const Text('MacosPopupButton'),
+                const SizedBox(height: 8),
+                MacosPopupButton<String>(
+                  value: popupValue,
+                  onChanged: (String? newValue) {
+                    setState(() {
+                      popupValue = newValue!;
+                    });
+                  },
+                  items: <String>['One', 'Two', 'Three', 'Four']
+                      .map<MacosPopupMenuItem<String>>((String value) {
+                    return MacosPopupMenuItem<String>(
+                      value: value,
+                      child: Text(value),
+                    );
+                  }).toList(),
+                ),
+                const SizedBox(height: 20),
+                const Text('MacosPopupButton (large list)'),
+                const SizedBox(height: 8),
+                MacosPopupButton<String>(
+                  value: languagePopupValue,
+                  onChanged: (String? newValue) {
+                    setState(() {
+                      languagePopupValue = newValue!;
+                    });
+                  },
+                  items:
+                      languages.map<MacosPopupMenuItem<String>>((String value) {
+                    return MacosPopupMenuItem<String>(
+                      value: value,
+                      child: Text(value),
+                    );
+                  }).toList(),
+                ),
+                const SizedBox(height: 20),
                 Row(
                   mainAxisAlignment: MainAxisAlignment.center,
                   children: [
@@ -227,3 +266,40 @@ class _ButtonsPageState extends State<ButtonsPage> {
     );
   }
 }
+
+const languages = [
+  "Mandarin Chinese",
+  "Spanish",
+  "English",
+  "Hindi/Urdu",
+  "Arabic",
+  "Bengali",
+  "Portuguese",
+  "Russian",
+  "Japanese",
+  "German",
+  "Thai",
+  "Greek",
+  "Nepali",
+  "Punjabi",
+  "Wu",
+  "French",
+  "Telugu",
+  "Vietnamese",
+  "Marathi",
+  "Korean",
+  "Tamil",
+  "Italian",
+  "Turkish",
+  "Cantonese/Yue",
+  "Urdu",
+  "Javanese",
+  "Egyptian Arabic",
+  "Gujarati",
+  "Iranian Persian",
+  "Indonesian",
+  "Polish",
+  "Ukrainian",
+  "Romanian",
+  "Dutch"
+];

example/macos/Podfile.lock

@@ -19,4 +19,4 @@ SPEC CHECKSUMS:
 
 PODFILE CHECKSUM: 6eac6b3292e5142cfc23bdeb71848a40ec51c14c
 
-COCOAPODS: 1.11.2
+COCOAPODS: 1.10.2

example/pubspec.lock

@@ -73,7 +73,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.10.1"
+    version: "0.11.0"
   matcher:
     dependency: transitive
     description:

lib/macos_ui.dart

@@ -16,6 +16,7 @@ export 'src/buttons/back_button.dart';
 export 'src/buttons/checkbox.dart';
 export 'src/buttons/help_button.dart';
 export 'src/buttons/icon_button.dart';
+export 'src/buttons/popup_button.dart';
 export 'src/buttons/push_button.dart';
 export 'src/buttons/radio_button.dart';
 export 'src/buttons/switch.dart';