Poly modal alert #524

hurnell · 2025-09-25T13:23:44Z

PolyModalAlert

A modal alert designed to do almost everything NSAlert can, with full UI flexibility.

Available options:

Multiple buttons
Multiple checkboxes
Combo box / dropdown menu
Text field
Configurable width

Usage

alert = iterm2.PolyModalAlert(_title, _subtitle, _windowId)

# alert.set_width(500) # 300 is the default

alert.add_button("button one")
alert.add_button("button two")
alert.add_button("button three")

alert.add_combobox_item("combobox item 1")
alert.add_combobox_item("combobox item 2 - default", 1)
alert.add_combobox_item("combobox item 3")


alert.add_checkbox_item('checkbox 1')
alert.add_checkbox_item('checkbox 2')
alert.add_checkbox_item('checkbox 3 - checked by default', 1)

alert.add_text_field('placeholder', 'default_text_field_value')

return await alert.async_run(connection)

return values

{
     'button': 'button three', 
     'tf_text': 'text you entered', 
     'combo': 'combobox item 1',
     'checks': ['checkbox 1’, 'checkbox 2']
}

…alert

gnachman · 2025-10-20T23:42:26Z

Sorry for the delay in getting to this. I've been swamped dealing with the release of 3.6.

gnachman · 2025-10-20T22:58:05Z

sources/iTermAlertBuiltInFunction.m

+        NSUInteger idx = 0;
+        for (id checkbox in checkboxes) {
+            NSButton *currentCheckbox = [[NSButton alloc] initWithFrame:NSMakeRect(59, vertOffset, 82, 32)];
+            [currentCheckbox setButtonType:NSButtonTypeSwitch];


This is overwritten on line 268

line 268 removed

gnachman · 2025-10-20T22:58:22Z

sources/iTermAlertBuiltInFunction.m

+        for (id checkbox in checkboxes) {
+            NSButton *currentCheckbox = [[NSButton alloc] initWithFrame:NSMakeRect(59, vertOffset, 82, 32)];
+            [currentCheckbox setButtonType:NSButtonTypeSwitch];
+            [currentCheckbox setTitle: checkbox];


Style nit: no space after a colon (here and in many other places)

updated formatting and code style

gnachman · 2025-10-20T22:58:31Z

sources/iTermAlertBuiltInFunction.m

+            [currentCheckbox setTitle: checkbox];
+            NSUInteger st = [[checkbox_defaults objectAtIndex: idx] intValue];
+            [currentCheckbox setState: st];
+            [currentCheckbox setButtonType:NSButtonTypeMomentaryLight]; //Set what type button You want


Remove these comments

gnachman · 2025-10-20T22:59:24Z

sources/iTermAlertBuiltInFunction.m

+
+@implementation iTermGetPolyModalAlertBuiltInFunction
+
+ (NSArray *) getCompletion:(NSMutableArray * ) items :(NSModalResponse ) tag :(NSString *) textFieldText :(NSArray *) buttons :(NSArray *) combobox_items {


Style nits: remove excess spaces in various places. Look at how method signatures look in existing code for guidance.

Use comboboxItems instead of combobox_items.

When possible, use lightweight generics for NSArray (e.g., NSArray<NSString *> *)

spaces cleaned with ⌃⌥⇧I

changed to comboboxItems.

changed to eg

buttons:(NSArray<NSString *> *)buttons
checkboxDefaults:(NSArray<NSNumber *> *)checkboxDefaults

gnachman · 2025-10-20T23:00:29Z

sources/iTermAlertBuiltInFunction.m

+
+ (NSArray *) getCompletion:(NSMutableArray * ) items :(NSModalResponse ) tag :(NSString *) textFieldText :(NSArray *) buttons :(NSArray *) combobox_items {
+    NSMutableArray *checkboxArray ;
+    if([items[1]  isEqual: @"checkbox"]){


Style nits: should be if ([items[i] isEqual:@"checkbox"])

Changed to
if ([items[1] isEqual:@"checkbox"]) excess whitespace removed

gnachman · 2025-10-20T23:33:56Z

sources/iTermAlertBuiltInFunction.m

+            NSUInteger st = [[checkbox_defaults objectAtIndex: idx] intValue];
+            [currentCheckbox setState: st];
+            [currentCheckbox setButtonType:NSButtonTypeMomentaryLight]; //Set what type button You want
+            [currentCheckbox setBezelStyle:NSBezelStylePush]; //Set what style You want


I don't think you need to change the bezel style for a standard checkbox.

gnachman · 2025-10-20T23:34:08Z

sources/iTermAlertBuiltInFunction.m

+            [currentCheckbox setTarget:self];
+            [checkboxViews addObject: currentCheckbox];
+            [addedViews addObject: currentCheckbox];
+            idx ++;


No space after idx

gnachman · 2025-10-20T23:37:01Z

sources/iTermAlertBuiltInFunction.m

+        NSMutableArray *checkboxViews = [[NSMutableArray alloc] initWithCapacity: [checkboxes count]];
+        NSUInteger idx = 0;
+        for (id checkbox in checkboxes) {
+            NSButton *currentCheckbox = [[NSButton alloc] initWithFrame:NSMakeRect(59, vertOffset, 82, 32)];


Define a file-scope constant for the magic numbers 59. 82 and 32 are unncessary; since this uses auto layout, I expect the system will ignore the initial sizes values.

NSButton *currentCheckbox = [[NSButton alloc] initWithFrame:NSZeroRect];

gnachman · 2025-10-20T23:39:00Z

api/library/python/iterm2/iterm2/alert.py

+        """Adds an array of checkbox items to the end of the list of
+        checkboxes."""
+        idx = 0
+        for item_text in items:


Use zip(item_text, defaults) to simplify this loop

assert len(items) == len(defaults), "items and defaults must have the same length." for item_text, default in zip(items, defaults): self.__checkbox_defaults.append(default) self.__checkboxes.append(item_text)

gnachman · 2025-10-20T23:39:25Z

api/library/python/iterm2/iterm2/alert.py

+            self.__combobox_default = item_text
+
+    def add_text_field(self, placeholder: str, default: str):
+        """add a text field to the alert """


Style nit: Use proper capitalization and punctuation

"""Add a text field to the alert."""

gnachman · 2025-10-27T15:58:58Z

api/library/python/iterm2/iterm2/alert.py

+
+@dataclass
+class PolyModalResult:
+    """Dedicate object to return for PolyModalAlert """


Typo: should be "Dedicated"

gnachman · 2025-10-27T16:01:40Z

sources/iTermAlertBuiltInFunction.m

+
+ (NSDictionary *)polyModalCompletion:(PolyModalItems *)polyModalItems
+                                  tag:(NSModalResponse)tag {
+    NSMutableDictionary *result = [NSMutableDictionary dictionary];


I believe the values are all strings? If so use lightweight generics:

NSMutableDictionary<NSString *, NSString *> *result = [NSMutableDictionary dictionary];

And also the return type for the method should be NSDictionary<NSString *, NSString *> *

gnachman · 2025-10-27T16:09:05Z

sources/iTermAlertBuiltInFunction.m

+    alert.informativeText = subtitle;
+    PolyModalItems *polyModalItems = [[PolyModalItems alloc] init];
+    polyModalItems.buttons = buttons;
+    for (NSString *buttonTitle in buttons) {


Ensure buttonTitle is a string since the type checker isn't able to do that for you (it only ensures that buttons is an array). See line 57 for an example.

gnachman · 2025-10-27T16:15:18Z

sources/iTermAlertBuiltInFunction.m

+                alertWidth:(NSNumber *)alertWidth
+                  windowID:(NSString *)windowID
+                completion:(iTermBuiltInFunctionCompletionBlock)completion {
+    NSAlert *alert = [[NSAlert alloc] init];


Add a check that checkboxes and checkboxDefaults have the same number of values. If they don't, call the completion block with an error and return early. See iTermArrayCountBuiltInFunction for an example of returning errors.

gnachman · 2025-10-27T16:15:48Z

sources/iTermAlertBuiltInFunction.m

+            currentCheckbox.buttonType = NSButtonTypeSwitch;
+            currentCheckbox.title = checkboxTitle;
+            currentCheckbox.state = [[checkboxDefaults objectAtIndex:idx] integerValue];
+            currentCheckbox.target = self;


You can remove this. Since there is no action, clicking the button won't invoke a method.

gnachman · 2025-10-27T16:19:30Z

sources/iTermAlertBuiltInFunction.m

+    NSWindow *window =
+        [[[iTermController sharedInstance] terminalWithGuid:windowID] window];
+    NSModalResponse responseTag;
+    if (window) {


Please verify that this lays out correctly in both macOS 26 and macOS 15. Typically we must call [alert layout] before running it. If you don't have a macOS 15 system to test with I can do this for you, just lmk

gnachman · 2025-10-27T16:20:44Z

sources/iTermAlertBuiltInFunction.m

+        textField.stringValue = textFieldParams[1];
+        textField.placeholderString = textFieldParams[0];
+        [stackViews addObject:textField];
+        polyModalItems.textField = textField;


When there is a text field, you probably want to make it first responder. Look at showAlertWithTextFieldAccessoryWithTitle:subtitle:placeholder:defaultValue:windowID:completion: for how to do this.

hurnell added 3 commits September 24, 2025 12:05

main changes for poly-modal-alert

7772adc

members for PolyModalAlert

166c023

Merge remote-tracking branch 'origin/master' into feature/poly-modal-…

ee0d5eb

…alert

gnachman requested changes Oct 20, 2025

View reviewed changes

hurnell added 9 commits October 25, 2025 16:44

formatting & code style

813fdbe

changed var names to camelCase

14e67a8

fix spacing

1cfcfb1

improve

3514257

rename params to conform to objective c code

35ad46e

more code style modernisation

e9e3040

just return object (that is created in obj c code)

aeef717

update conform review

c4cdb18

fix pylint errors

85ba591

hurnell requested a review from gnachman October 27, 2025 13:32

gnachman requested changes Oct 27, 2025

View reviewed changes


		@implementation iTermGetPolyModalAlertBuiltInFunction

		+ (NSArray ) getCompletion:(NSMutableArray ) items :(NSModalResponse ) tag :(NSString ) textFieldText :(NSArray ) buttons :(NSArray *) combobox_items {

Uh oh!

Poly modal alert #524

Are you sure you want to change the base?

Poly modal alert #524

Uh oh!

Conversation

hurnell commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PolyModalAlert

Usage

return values

Uh oh!

gnachman commented Oct 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hurnell commented Sep 25, 2025 •

edited

Loading