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()

https://s3-us-west-2.amazonaws.com/secure.notion-static.com/e8779cdc-d099-40d6-b4f9-e5a9d553270e/2019-08-30_09_01_08-Reload.png

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()

https://s3-us-west-2.amazonaws.com/secure.notion-static.com/fa914130-d0ee-4e97-bfa3-97857e2184bf/2019-08-30_09_02_37-Keynotes.png

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()

https://s3-us-west-2.amazonaws.com/secure.notion-static.com/5c945825-c8b3-419e-837c-7181939ba021/2019-08-30_09_07_38-View_Ordering_Tool.png

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>"
        })

https://s3-us-west-2.amazonaws.com/secure.notion-static.com/1db411a2-1915-4ca8-a131-776e83349fbd/2019-08-30_08_58_08-Window.png

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()

https://s3-us-west-2.amazonaws.com/secure.notion-static.com/f331dc91-8593-4221-919e-4eccb8eaecfe/2019-08-30_09_22_03-Autodesk_Revit_2019.2_-_Project1.rvt_-_Floor_Plan__Level_1.png

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']))

https://s3-us-west-2.amazonaws.com/secure.notion-static.com/aeadb2f5-6d70-4cc1-85f6-081ca7c4a60d/2019-08-30_09_16_12-Command_Options.png

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

https://s3-us-west-2.amazonaws.com/secure.notion-static.com/5664562c-3f8a-4e65-852a-f018beb37e5d/2019-08-30_09_23_56-Autodesk_Revit_2019.2_-_Project1.rvt_-_Floor_Plan__Level_1.png

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 )