Enhance: Add shield, information, and error icons to forms.alert()

[smit-8462]

Add shield, information, and error icons to forms.alert()

Description

The icon parameter is introduced in forms.alert() for specifying the TaskDialog icons to be used for alert form.

Following changes are implemented in this PR -

• Add support for "shield", "information", and "error" icons derived from Revit API's TaskDialogIcon enum TaskDialog class, in addition to existing "warning" icon.
• Introduced a new icon-mapping logic for mapping of "shield", "information", and "error" by using icon parameter.
• The original icon-mapping logic of using warn_icon parameter for "warn" icon is preserved for full backward
  compatibility.
• When only warn_icon parameter is used, original icon-mapping logic will be used.
• But if only icon parameter is used, new icon-mapping logic will be used.
• If both warn_icon and icon parameters are passed, then icon parameter will take precedence over warn_icon parameter, and new icon-mapping logic will be used.

No breaking changes, existing calls to forms.alert(), with or without warn_icon will behave exactly as before.

---

Checklist

Before submitting your pull request, ensure the following requirements are met:

• Code follows the PEP 8 style guide.
• Code has been formatted with Black using the command:

  pipenv run black {source_file_or_directory}

• Changes are tested and verified to work as expected.

---

Related Issues

• Resolves Enhance: Add remaining TaskDialog icons in forms.alert #3551

---

Additional Notes

Tested manually in Revit 2025.4 via pyRevit reload:

Command	Expected Result	Image
forms.alert("Default (Warning) icon")	Warning icon (unchanged default)
forms.alert("No icon shown", warn_icon=False)	No icon (unchanged)
forms.alert("Shield icon", icon="shield")	Shield icon (new)
forms.alert("Information icon", icon="information")	Information icon (new)
forms.alert("Error icon", icon="error")	Error icon (new)
forms.alert("Warning icon", icon="warning")	Warning icon (new, explicit)
forms.alert("No icon (incorrect input)", icon="bogus")	No icon (invalid icon key)
forms.alert("Warning icon (empty input)", icon="")	Warning icon (empty icon falls back to warn_icon default)
forms.alert("Icon conflict", warn_icon=True, icon="shield")	Shield icon (icon takes precedence)
forms.alert("Icon conflict", warn_icon=False, icon="warning")	Warning icon (icon takes precedence)

Reference: TaskDialogIcon Enumeration – Revit API Docs

Thank you for contributing to pyRevit! 🎉

[devloai]

PR Summary:

• Adds an icon parameter to forms.alert() supporting "shield", "information", "error", and "warning" icons mapped to Revit API's TaskDialogIcon enum.
• Preserves full backward compatibility: the legacy warn_icon boolean path is used when icon is not provided; icon takes precedence when both are passed.
• Also includes unrelated black formatting touch-ups (blank lines after imports, quote normalization, FamilyParamOption reformatting).

Review Summary:

The core feature is well-designed and backward-compatible — the legacy warn_icon path is correctly preserved and the new icon parameter cleanly extends the API. One high-severity issue was found in the icon-mapping block: the PR's own test table contradicts the actual code behavior for the two "icon conflict" cases (the "Expected Result" column text is wrong; the code correctly makes icon take precedence), and the docstring should state the precedence rule explicitly. Additionally, invalid icon values (e.g. typos like "erorr") silently fall back to no icon with zero feedback — per the repo guideline that configuration errors should never fail silently, this should log a warning via mlogger.warning(...). The redundant if icon else "" guard inside the .get() call is dead code given the outer if icon: check. IronPython compatibility, black formatting, and PEP 8 naming are all respected.

Suggestions

• Add unit tests covering icon_map lookup, precedence over warn_icon, and invalid-icon fallback behavior. Apply
• Update the pyRevit API reference docs to document the new icon parameter and its valid values. Apply

[Copilot]

Pull request overview

This PR extends the widely-used forms.alert() helper in pyRevit's IronPython forms backend (pyrevitlib/pyrevit/forms/_ipy.py) so callers can select a TaskDialog icon beyond the existing warning/none options. It resolves issue #3551 by exposing the Revit API TaskDialogIcon values for "shield", "information", and "error" (plus explicit "warning") through a new icon string parameter, while preserving the legacy warn_icon boolean behavior for full backward compatibility.

Changes:

• Added an icon keyword parameter to alert() with an icon-mapping dictionary; a non-empty icon takes precedence over warn_icon, and unknown values log a warning and fall back to no icon.
• Preserved the original warn_icon logic path when icon is empty, so existing callers are unaffected.
• Applied incidental Black-style formatting (blank lines after imports, single→double quotes, wrapped FamilyParamOption.__init__ signature) and updated the docstring.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[smit-8462]

Grammar fixed (as per bot).