Effective Input

Alerts

Use forms.alert() and forms.alert_ifnot() to send alerts to the user and ask quick questions

from pyrevit import forms

res = forms.alert("Reloading increases the memory footprint and is "
                  "automatically called by pyRevit when necessary.\\n\\n"
                  "pyRevit developers can manually reload when:\\n"
                  "    - New buttons are added.\\n"
                  "    - Buttons have been removed.\\n"
                  "    - Button icons have changed.\\n"
                  "    - Base C# code has changed.\\n"
                  "    - Value of pyRevit parameters\\n"
                  "      (e.g. __title__, __doc__, ...) have changed.\\n"
                  "    - Cached engines need to be cleared.\\n\\n"
                  "Are you sure you want to reload?",
                  ok=False, yes=True, no=True)
if res:
    do_stuff()

Use the options argument to show options to the user on the alert window

from pyrevit import forms

res = forms.alert("Existing keynote file needs to be converted to "
                  "a format usable by this tool. The resulting keynote "
                  "file is still readble by Revit and could be shared "
                  "with other projects. Users should NOT be making changes to "
                  "the existing keynote file during the conversion process.\\n"
                  "Are you sure you want to convert?",
                  options=["Convert",
                           "Select a different keynote file",
                           "Give me more info"])
if res == "Convert":
    do_stuff()

Use the exitscript option to end the script if user says No, or hits OK

from pyrevit import forms

forms.alert('You must be on a sheet to use this tool.', exitscript=True)
# if user says no, the alert function will end the script
# and the command does not execute the next line
do_stuff()

Use the alert_ifnot to check for a condition and show the alert based on the results

# asks "Are you sure?" if value > 12
# exits the script if user says No
forms.alert_ifnot(value > 12,
                  'Are you sure?',
                  yes=True, no=True, exitscript=True)

Toast

Use forms.toast() to send a toast notification (Windows 10 only)

from pyrevit import forms

forms.toast(
    "Hello World!",
    title="My Script",
    appid="MyAPP",
    click="<https://eirannejad.github.io/pyRevit/>",
    actions={
        "Open Google":"<https://google.com>",
        "Open Toast64":"<https://github.com/go-toast/toast>"
        })

Command Options

Use the forms.CommandSwitchWindow to present options to the user and ask for a choice

from pyrevit import forms

selected_option = forms.CommandSwitchWindow.show(
    ['Option_1', 'Option 2', 'Option 3', 'Option 4', 'Option 5'],
     message='Select Option:',
)

if selected_option == 'Option 2':
    do_stuff()

Use the switches option to provide toggle switches to modify your command behaviour

selected_option, switches = \\
    forms.CommandSwitchWindow.show(
        ['Option_1', 'Option 2', 'Option 3', 'Option 4', 'Option 5'],
        switches=['Switch 1', 'Switch 2'],
        message='Select Option:',
        recognize_access_key=True
        )

if selected_option:
    print('Selected Option: {}'
          '\\n Switch 1 = {}'
          '\\n Switch 2 = {}'.format(selected_option,
                                    switches['Switch 1'],
                                    switches['Switch 2']))

For example the Rename Views tool provides a switch to print a report or not

The recognize_access_key option will translate the _ characters in the option name to ALT+? commands. In the example above Option_1 configures the window to allow the ALT+1 combination to select this option. (This is a WPF feature )