_ipy

Reusable WPF forms for pyRevit.

Examples:

from pyrevit.forms import WPFWindow

Attributes

mlogger = get_logger(__name__) module-attribute

DEFAULT_CMDSWITCHWND_WIDTH = 600 module-attribute

DEFAULT_SEARCHWND_WIDTH = 600 module-attribute

DEFAULT_SEARCHWND_HEIGHT = 100 module-attribute

DEFAULT_INPUTWINDOW_WIDTH = 500 module-attribute

DEFAULT_INPUTWINDOW_HEIGHT = 600 module-attribute

DEFAULT_RECOGNIZE_ACCESS_KEY = False module-attribute

WPF_HIDDEN = framework.Windows.Visibility.Hidden module-attribute

WPF_COLLAPSED = framework.Windows.Visibility.Collapsed module-attribute

WPF_VISIBLE = framework.Windows.Visibility.Visible module-attribute

XAML_FILES_DIR = op.dirname(__file__) module-attribute

ParamDef = namedtuple('ParamDef', ['name', 'istype', 'definition', 'isreadonly', 'isunit', 'storagetype', 'displayvalue', 'hasvalue', 'grouptype', 'isshared', 'paramid']) module-attribute

Parameter definition tuple. Attributes: name (str): parameter name istype (bool): true if type parameter, otherwise false definition (Autodesk.Revit.DB.Definition): parameter definition object isreadonly (bool): true if the parameter value can't be edited isunit (bool): true if its ForgeTypeId is measurable storagetype (Autodesk.Revit.DB.StorageType): String, Integer, Double or ElementId displayvalue (str): display string of the current parameter value, or None hasvalue (bool): true if the parameter has a value to display grouptype (str): name of parameter group isshared (bool): is the parameter shared paramid (str): stringified parameter ElementId (integer id)

Classes

reactive(getter)

Bases: property

Decorator for WPF bound properties.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, getter):
    def newgetter(ui_control):
        try:
            return getter(ui_control)
        except AttributeError:
            return None

    super(reactive, self).__init__(newgetter)

Functions

setter(setter)

Property setter.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setter(self, setter):
    """Property setter."""

    def newsetter(ui_control, newvalue):
        oldvalue = self.fget(ui_control)
        if oldvalue != newvalue:
            setter(ui_control, newvalue)
            ui_control.OnPropertyChanged(setter.__name__)

    return property(
        fget=self.fget, fset=newsetter, fdel=self.fdel, doc=self.__doc__
    )

Reactive

Bases: INotifyPropertyChanged

WPF property updator base mixin.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def add_PropertyChanged(self, value):
    """Called when a property is added to the object."""
    self.PropertyChanged += value

remove_PropertyChanged(value)

Called when a property is removed from the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def remove_PropertyChanged(self, value):
    """Called when a property is removed from the object."""
    self.PropertyChanged -= value

OnPropertyChanged(prop_name)

Called when a property is changed.

Parameters:

Name	Type	Description	Default
prop_name	str	property name	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def OnPropertyChanged(self, prop_name):
    """Called when a property is changed.

    Args:
        prop_name (str): property name
    """
    if self._propertyChangedCaller:
        args = ComponentModel.PropertyChangedEventArgs(prop_name)
        self._propertyChangedCaller(self, args)

WindowToggler(window)

Bases: object

Context manager to toggle window visibility.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, window):
    self._window = window

WPFWindow(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Bases: _WPFMixin, Window

WPF Window base class for all pyRevit forms.

Parameters:

Name	Type	Description	Default
xaml_source	str	xaml source filepath or xaml content	required
literal_string	bool	xaml_source contains xaml content, not filepath	False
handle_esc	bool	handle Escape button and close the window	True
set_owner	bool	set the owner of window to host app window	True

Examples:

from pyrevit import forms
layout = '<Window ' \
         'xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" ' \
         'xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" ' \
         'ShowInTaskbar="False" ResizeMode="NoResize" ' \
         'WindowStartupLocation="CenterScreen" ' \
         'HorizontalContentAlignment="Center">' \
         '</Window>'
w = forms.WPFWindow(layout, literal_string=True)
w.show()

Initialize WPF window and resources.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Initialize WPF window and resources."""
    # load xaml
    self.load_xaml(
        xaml_source,
        literal_string=literal_string,
        handle_esc=handle_esc,
        set_owner=set_owner,
    )

Attributes

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

Functions

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

handle_input_key(sender, args)

Handle keyboard input and close the window on Escape.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input and close the window on Escape."""
    if args.Key == Input.Key.Escape:
        self.Close()

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show(modal=False)

Show window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show(self, modal=False):
    """Show window."""
    if modal:
        return self.ShowDialog()
    # else open non-modal
    self.Show()

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

WPFPanel()

Bases: _WPFMixin, Page

WPF panel base class for all pyRevit dockable panels.

Subclass this, set the three required class attributes, then register
and open the panel through the module-level helpers.

Required class attributes:
    panel_id (str): stable UUID string identifying the panel in Revit.
    panel_source (str): XAML filename (resolved relative to the command).
    panel_title (str): title displayed in the panel chrome.

Optional class attributes:
    initial_state (UI.DockablePaneState):
        initial docking position; Revit picks a default when None.
    editor_interaction (UI.EditorInteractionType):
        how the panel behaves while an editor is active.
    contextual_help (UI.ContextualHelp):
        F1 help associated with the pane.

Examples:

python from pyrevit import forms import Autodesk.Revit.UI as UI state = UI.DockablePaneState() state.DockPosition = UI.DockPosition.Right class MyPanel(forms.WPFPanel): panel_id = "181e05a4-28f6-4311-8a9f-d2aa528c8755" panel_source = "MyPanel.xaml" panel_title = "My Panel" initial_state = state forms.register_dockable_panel(MyPanel) # open from any command button forms.open_dockable_panel(MyPanel) # retrieve the live instance from anywhere dockable_pane = forms.get_dockable_panel(MyPanel)

Initialize WPF panel and resources.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self):
    """Initialize WPF panel and resources."""
    if not self.panel_id:
        raise PyRevitException('"panel_id" class attribute is not set')
    if not self.panel_source:
        raise PyRevitException('"panel_source" class attribute is not set')
    if not self.panel_title:
        raise PyRevitException('"panel_title" class attribute is not set')

    self.load_xaml(self.panel_source)

Attributes

panel_id = None class-attribute instance-attribute

panel_source = None class-attribute instance-attribute

panel_title = None class-attribute instance-attribute

initial_state = None class-attribute instance-attribute

editor_interaction = None class-attribute instance-attribute

contextual_help = None class-attribute instance-attribute

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

Functions

load_xaml(xaml_source, literal_string=False)

Load the panel XAML file.

Supports the full locale-fallback chain (see _resolve_xaml_source) and can accept raw XAML content via literal_string, matching WPFWindow.

Parameters:

Name	Type	Description	Default
xaml_source	str	XAML content string or file path.	required
literal_string	bool	True when xaml_source is raw content.	False

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(self, xaml_source, literal_string=False):
    """Load the panel XAML file.

    Supports the full locale-fallback chain (see _resolve_xaml_source) and
    can accept raw XAML content via literal_string, matching WPFWindow.

    Args:
        xaml_source (str): XAML content string or file path.
        literal_string (bool): True when xaml_source is raw content.
    """
    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))
    self.thread_id = framework.get_current_thread_id()

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

TemplateUserInputWindow(context, title, width, height, **kwargs)

Bases: WPFWindow

Base class for pyRevit user input standard forms.

Parameters:

Name	Type	Description	Default
context	any	window context element(s)	required
title	str	window title	required
width	int	window width	required
height	int	window height	required
**kwargs	Any	other arguments to be passed to :func:_setup	{}

Initialize user input window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, context, title, width, height, **kwargs):
    """Initialize user input window."""
    WPFWindow.__init__(
        self, op.join(XAML_FILES_DIR, self.xaml_source), handle_esc=True
    )
    if title:
        self.Title = title
    else:
        try:
            localized_title = self.get_locale_string(self.default_title_key)
        except System.Windows.ResourceReferenceKeyNotFoundException:
            localized_title = None
        self.Title = (
            localized_title if isinstance(localized_title, str) else "User Input"
        )
    self.Width = width
    self.Height = height

    self._context = context
    self.response = None

    # parent window?
    owner = kwargs.get("owner", None)
    if owner:
        # set wpf windows directly
        self.Owner = owner
        self.WindowStartupLocation = (
            framework.Windows.WindowStartupLocation.CenterOwner
        )

    self._setup(**kwargs)

Attributes

xaml_source = 'BaseWindow.xaml' class-attribute instance-attribute

default_title_key = 'pyRevit.DefaultWindowTitle' class-attribute instance-attribute

Title = title instance-attribute

Width = width instance-attribute

Height = height instance-attribute

response = None instance-attribute

Owner = owner instance-attribute

WindowStartupLocation = framework.Windows.WindowStartupLocation.CenterOwner instance-attribute

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

Functions

show(context, title=None, width=DEFAULT_INPUTWINDOW_WIDTH, height=DEFAULT_INPUTWINDOW_HEIGHT, **kwargs) classmethod

Show user input window.

Parameters:

Name	Type	Description	Default
context	any	window context element(s)	required
title	str	window title	None
width	int	window width	DEFAULT_INPUTWINDOW_WIDTH
height	int	window height	DEFAULT_INPUTWINDOW_HEIGHT
**kwargs	any	other arguments to be passed to window	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@classmethod
def show(
    cls,
    context,  # pylint: disable=W0221
    title=None,
    width=DEFAULT_INPUTWINDOW_WIDTH,
    height=DEFAULT_INPUTWINDOW_HEIGHT,
    **kwargs
):
    """Show user input window.

    Args:
        context (any): window context element(s)
        title (str): window title
        width (int): window width
        height (int): window height
        **kwargs (any): other arguments to be passed to window
    """
    dlg = cls(context, title, width, height, **kwargs)
    dlg.ShowDialog()
    return dlg.response

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

handle_input_key(sender, args)

Handle keyboard input and close the window on Escape.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input and close the window on Escape."""
    if args.Key == Input.Key.Escape:
        self.Close()

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

TemplateListItem(orig_item, checked=False, checkable=True, name_attr=None)

Bases: Reactive

Base class for checkbox option wrapping another object.

Initialize the checkbox option and wrap given obj.

Parameters:

Name	Type	Description	Default
orig_item	any	Object to wrap (must have name property or be convertable to string with str()	required
checked	bool	Initial state. Defaults to False	False
checkable	bool	Use checkbox for items	True
name_attr	str	Get this attribute of wrapped object as name	None

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, orig_item, checked=False, checkable=True, name_attr=None):
    """Initialize the checkbox option and wrap given obj.

    Args:
        orig_item (any): Object to wrap (must have name property
                         or be convertable to string with str()
        checked (bool): Initial state. Defaults to False
        checkable (bool): Use checkbox for items
        name_attr (str): Get this attribute of wrapped object as name
    """
    super(TemplateListItem, self).__init__()
    self.item = orig_item
    self.state = checked
    self._nameattr = name_attr
    self._checkable = checkable

Attributes

item = orig_item instance-attribute

state = checked instance-attribute

name property

Name property.

checkable property writable

List Item CheckBox Visibility.

Functions

unwrap()

Unwrap and return wrapped object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item

checked(value)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@checked.setter
def checked(self, value):
    self.state = value

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def add_PropertyChanged(self, value):
    """Called when a property is added to the object."""
    self.PropertyChanged += value

remove_PropertyChanged(value)

Called when a property is removed from the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def remove_PropertyChanged(self, value):
    """Called when a property is removed from the object."""
    self.PropertyChanged -= value

OnPropertyChanged(prop_name)

Called when a property is changed.

Parameters:

Name	Type	Description	Default
prop_name	str	property name	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def OnPropertyChanged(self, prop_name):
    """Called when a property is changed.

    Args:
        prop_name (str): property name
    """
    if self._propertyChangedCaller:
        args = ComponentModel.PropertyChangedEventArgs(prop_name)
        self._propertyChangedCaller(self, args)

SelectFromList(context, title, width, height, **kwargs)

Bases: TemplateUserInputWindow

Standard form to select from a list of items.

Any object can be passed in a list to the context argument. This class wraps the objects passed to context, in TemplateListItem. This class provides the necessary mechanism to make this form work both for selecting items from a list, and from a list of checkboxes. See the list of arguments below for additional options and features.

Parameters:

Name	Type	Description	Default
context	list[str] or dict[list[str]]	list of items to be selected from OR dict of list of items to be selected from. use dict when input items need to be grouped e.g. List of sheets grouped by sheet set.	required
title	str	window title. see super class for defaults.	required
width	int	window width. see super class for defaults.	required
height	int	window height. see super class for defaults.	required

Other Parameters:

Name	Type	Description
button_name	str	name of select button. defaults to 'Select'
name_attr	str	object attribute that should be read as item name.
multiselect	bool	allow multi-selection (uses check boxes). defaults to False
info_panel	bool	show information panel and fill with .description property of item
return_all	bool	return all items. This is handly when some input items have states and the script needs to check the state changes on all items. This options works in multiselect mode only. defaults to False
filterfunc	function	filter function to be applied to context items.
resetfunc	function	reset function to be called when user clicks on Reset button
group_selector_title	str	title for list group selector. defaults to 'List Group'
default_group	str	name of defautl group to be selected
sort_groups	str	Determines the sorting type applied to the list groups. This attribute can take one of the following values: 'sorted': This will sort the groups in standard alphabetical order 'natural': This will sort the groups in a manner that is more intuitive for human perception, especially when there are numbers involved. 'unsorted': The groups will maintain the original order in which they were provided, without any reordering. Defaults to 'sorted'.

Examples:

from pyrevit import forms
items = ['item1', 'item2', 'item3']
forms.SelectFromList.show(items, button_name='Select Item')
['item1']

from pyrevit import forms
ops = [viewsheet1, viewsheet2, viewsheet3]
res = forms.SelectFromList.show(ops,
                                multiselect=False,
                                name_attr='Name',
                                button_name='Select Sheet')

from pyrevit import forms
ops = {'Sheet Set A': [viewsheet1, viewsheet2, viewsheet3],
       'Sheet Set B': [viewsheet4, viewsheet5, viewsheet6]}
res = forms.SelectFromList.show(ops,
                                multiselect=True,
                                name_attr='Name',
                                group_selector_title='Sheet Sets',
                                button_name='Select Sheets',
                                sort_groups='sorted')

This module also provides a wrapper base class :obj:TemplateListItem for when the checkbox option is wrapping another element, e.g. a Revit ViewSheet. Derive from this base class and define the name property to customize how the checkbox is named on the dialog.

from pyrevit import forms
class MyOption(forms.TemplateListItem):
   @property
   def name(self):
       return '{} - {}{}'.format(self.item.SheetNumber,
                                 self.item.SheetNumber)
ops = [MyOption('op1'), MyOption('op2', True), MyOption('op3')]
res = forms.SelectFromList.show(ops,
                                multiselect=True,
                                button_name='Select Item')
[bool(x) for x in res]  # or [x.state for x in res]
[True, False, True]

Initialize user input window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, context, title, width, height, **kwargs):
    """Initialize user input window."""
    WPFWindow.__init__(
        self, op.join(XAML_FILES_DIR, self.xaml_source), handle_esc=True
    )
    if title:
        self.Title = title
    else:
        try:
            localized_title = self.get_locale_string(self.default_title_key)
        except System.Windows.ResourceReferenceKeyNotFoundException:
            localized_title = None
        self.Title = (
            localized_title if isinstance(localized_title, str) else "User Input"
        )
    self.Width = width
    self.Height = height

    self._context = context
    self.response = None

    # parent window?
    owner = kwargs.get("owner", None)
    if owner:
        # set wpf windows directly
        self.Owner = owner
        self.WindowStartupLocation = (
            framework.Windows.WindowStartupLocation.CenterOwner
        )

    self._setup(**kwargs)

Attributes

in_check = False class-attribute instance-attribute

in_uncheck = False class-attribute instance-attribute

xaml_source = 'SelectFromList.xaml' class-attribute instance-attribute

default_title_key = 'SelectFromList.DefaultTitle' class-attribute instance-attribute

use_regex property

Is using regex?

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

Title = title instance-attribute

Width = width instance-attribute

Height = height instance-attribute

response = None instance-attribute

Owner = owner instance-attribute

WindowStartupLocation = framework.Windows.WindowStartupLocation.CenterOwner instance-attribute

Functions

toggle_all(sender, args)

Handle toggle all button to toggle state of all check boxes.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def toggle_all(self, sender, args):  # pylint: disable=W0613
    """Handle toggle all button to toggle state of all check boxes."""
    self._set_states(flip=True)

check_all(sender, args)

Handle check all button to mark all check boxes as checked.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_all(self, sender, args):  # pylint: disable=W0613
    """Handle check all button to mark all check boxes as checked."""
    self._set_states(state=True)

uncheck_all(sender, args)

Handle uncheck all button to mark all check boxes as un-checked.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def uncheck_all(self, sender, args):  # pylint: disable=W0613
    """Handle uncheck all button to mark all check boxes as un-checked."""
    self._set_states(state=False)

check_selected(sender, args)

Mark selected checkboxes as checked.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_selected(self, sender, args):  # pylint: disable=W0613
    """Mark selected checkboxes as checked."""
    if not self.in_check:
        try:
            self.in_check = True
            self._set_states(state=True, selected=True)
        finally:
            self.in_check = False

uncheck_selected(sender, args)

Mark selected checkboxes as unchecked.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def uncheck_selected(self, sender, args):  # pylint: disable=W0613
    """Mark selected checkboxes as unchecked."""
    if not self.in_uncheck:
        try:
            self.in_uncheck = True
            self._set_states(state=False, selected=True)
        finally:
            self.in_uncheck = False

button_reset(sender, args)

Handle reset button click.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def button_reset(self, sender, args):  # pylint: disable=W0613
    """Handle reset button click."""
    if self.reset_func:
        all_items = self.list_lb.ItemsSource
        self.reset_func(all_items)

button_select(sender, args)

Handle select button click.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def button_select(self, sender, args):  # pylint: disable=W0613
    """Handle select button click."""
    self.response = self._get_options()
    self.Close()

search_txt_changed(sender, args)

Handle text change in search box.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def search_txt_changed(self, sender, args):  # pylint: disable=W0613
    """Handle text change in search box."""
    if self.info_panel:
        self._toggle_info_panel(state=False)

    if self.search_tb.Text == "":
        self.hide_element(self.clrsearch_b)
    else:
        self.show_element(self.clrsearch_b)

    self._list_options(option_filter=self.search_tb.Text)

selection_changed(sender, args)

Handle selection change.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def selection_changed(self, sender, args):
    """Handle selection change."""
    if self.info_panel:
        self._toggle_info_panel(state=False)

    self._list_options(option_filter=self.search_tb.Text)

selected_item_changed(sender, args)

Handle selected item change.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def selected_item_changed(self, sender, args):
    """Handle selected item change."""
    if self.info_panel and self.list_lb.SelectedItem is not None:
        self._toggle_info_panel(state=True)
        self.infoData.Text = getattr(self.list_lb.SelectedItem, "description", "")

toggle_regex(sender, args)

Activate regex in search.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def toggle_regex(self, sender, args):
    """Activate regex in search."""
    self.regexToggle_b.Content = (
        self.Resources["regexIcon"]
        if self.use_regex
        else self.Resources["filterIcon"]
    )
    self.search_txt_changed(sender, args)
    self.search_tb.Focus()

clear_search(sender, args)

Clear search box.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def clear_search(self, sender, args):  # pylint: disable=W0613
    """Clear search box."""
    self.search_tb.Text = " "
    self.search_tb.Clear()
    self.search_tb.Focus()

show(context, title=None, width=DEFAULT_INPUTWINDOW_WIDTH, height=DEFAULT_INPUTWINDOW_HEIGHT, exitscript=False, **kwargs) classmethod

Show user input window. Args: context (any): window context element(s) width: ... height: ... exitscript: exit the script if the user cancels the dialog. Defaults to False

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@classmethod
def show(
    cls,
    context,
    title=None,
    width=DEFAULT_INPUTWINDOW_WIDTH,
    height=DEFAULT_INPUTWINDOW_HEIGHT,
    exitscript=False,
    **kwargs
):
    """Show user input window.
    Args:
        context (any): window context element(s)
        width: ...
        height: ...
        exitscript: exit the script if the user cancels the dialog. Defaults to False
    """
    dlg = cls(context, title, width, height, **kwargs)
    dlg.ShowDialog()
    if exitscript and not dlg.response:
        sys.exit()
    return dlg.response

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

handle_input_key(sender, args)

Handle keyboard input and close the window on Escape.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input and close the window on Escape."""
    if args.Key == Input.Key.Escape:
        self.Close()

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

CommandSwitchWindow(context, title, width, height, **kwargs)

Bases: TemplateUserInputWindow

Standard form to select from a list of command options.

Other Parameters:

Name	Type	Description
context	list[str]	list of command options to choose from
switches	list[str]	list of on/off switches
message	str	window title message
config	dict	dictionary of config dicts for options or switches
recognize_access_key	bool	recognize '_' as mark of access key

Returns:

Type	Description
str | tuple[str, dict]	name of selected option. if switches option is used, returns a tuple of selection option name and dict of switches

Examples:

This is an example with series of command options:

from pyrevit import forms
ops = ['option1', 'option2', 'option3', 'option4']
forms.CommandSwitchWindow.show(ops, message='Select Option')
'option2'

A more advanced example of combining command options, on/off switches, and option or switch configuration options:

from pyrevit import forms
ops = ['option1', 'option2', 'option3', 'option4']
switches = ['switch1', 'switch2']
cfgs = {'option1': { 'background': '0xFF55FF'}}
rops, rswitches = forms.CommandSwitchWindow.show(
    ops,
    switches=switches,
    message='Select Option',
    config=cfgs,
    recognize_access_key=False
    )
rops
'option2'
rswitches
{'switch1': False, 'switch2': True}

Initialize user input window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, context, title, width, height, **kwargs):
    """Initialize user input window."""
    WPFWindow.__init__(
        self, op.join(XAML_FILES_DIR, self.xaml_source), handle_esc=True
    )
    if title:
        self.Title = title
    else:
        try:
            localized_title = self.get_locale_string(self.default_title_key)
        except System.Windows.ResourceReferenceKeyNotFoundException:
            localized_title = None
        self.Title = (
            localized_title if isinstance(localized_title, str) else "User Input"
        )
    self.Width = width
    self.Height = height

    self._context = context
    self.response = None

    # parent window?
    owner = kwargs.get("owner", None)
    if owner:
        # set wpf windows directly
        self.Owner = owner
        self.WindowStartupLocation = (
            framework.Windows.WindowStartupLocation.CenterOwner
        )

    self._setup(**kwargs)

Attributes

xaml_source = 'CommandSwitchWindow.xaml' class-attribute instance-attribute

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

default_title_key = 'pyRevit.DefaultWindowTitle' class-attribute instance-attribute

Title = title instance-attribute

Width = width instance-attribute

Height = height instance-attribute

response = None instance-attribute

Owner = owner instance-attribute

WindowStartupLocation = framework.Windows.WindowStartupLocation.CenterOwner instance-attribute

Functions

handle_click(sender, args)

Handle mouse click.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_click(self, sender, args):  # pylint: disable=W0613
    """Handle mouse click."""
    self.Close()

handle_input_key(sender, args)

Handle keyboard inputs.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):
    """Handle keyboard inputs."""
    if args.Key == Input.Key.Escape:
        if self.search_tb.Text:
            self.search_tb.Text = ""
        else:
            self.Close()
    elif args.Key == Input.Key.Enter:
        active_button = self._get_active_button()
        if active_button:
            if isinstance(
                active_button, framework.Controls.Primitives.ToggleButton
            ):
                return
            self.process_option(active_button, None)
            args.Handled = True
    elif (
        args.Key != Input.Key.Tab
        and args.Key != Input.Key.Space
        and args.Key != Input.Key.LeftShift
        and args.Key != Input.Key.RightShift
    ):
        self.search_tb.Focus()

search_txt_changed(sender, args)

Handle text change in search box.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def search_txt_changed(self, sender, args):  # pylint: disable=W0613
    """Handle text change in search box."""
    self._filter_options(option_filter=self.search_tb.Text)

process_option(sender, args)

Handle click on command option button.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def process_option(self, sender, args):  # pylint: disable=W0613
    """Handle click on command option button."""
    self.Close()
    if sender:
        self._setup_response(response=sender.Content)

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show(context, title=None, width=DEFAULT_INPUTWINDOW_WIDTH, height=DEFAULT_INPUTWINDOW_HEIGHT, **kwargs) classmethod

Show user input window.

Parameters:

Name	Type	Description	Default
context	any	window context element(s)	required
title	str	window title	None
width	int	window width	DEFAULT_INPUTWINDOW_WIDTH
height	int	window height	DEFAULT_INPUTWINDOW_HEIGHT
**kwargs	any	other arguments to be passed to window	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@classmethod
def show(
    cls,
    context,  # pylint: disable=W0221
    title=None,
    width=DEFAULT_INPUTWINDOW_WIDTH,
    height=DEFAULT_INPUTWINDOW_HEIGHT,
    **kwargs
):
    """Show user input window.

    Args:
        context (any): window context element(s)
        title (str): window title
        width (int): window width
        height (int): window height
        **kwargs (any): other arguments to be passed to window
    """
    dlg = cls(context, title, width, height, **kwargs)
    dlg.ShowDialog()
    return dlg.response

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

GetValueWindow(context, title, width, height, **kwargs)

Bases: TemplateUserInputWindow

Standard form to get simple values from user.

Examples:

from pyrevit import forms
items = ['item1', 'item2', 'item3']
forms.SelectFromList.show(items, button_name='Select Item')
['item1']

Initialize user input window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, context, title, width, height, **kwargs):
    """Initialize user input window."""
    WPFWindow.__init__(
        self, op.join(XAML_FILES_DIR, self.xaml_source), handle_esc=True
    )
    if title:
        self.Title = title
    else:
        try:
            localized_title = self.get_locale_string(self.default_title_key)
        except System.Windows.ResourceReferenceKeyNotFoundException:
            localized_title = None
        self.Title = (
            localized_title if isinstance(localized_title, str) else "User Input"
        )
    self.Width = width
    self.Height = height

    self._context = context
    self.response = None

    # parent window?
    owner = kwargs.get("owner", None)
    if owner:
        # set wpf windows directly
        self.Owner = owner
        self.WindowStartupLocation = (
            framework.Windows.WindowStartupLocation.CenterOwner
        )

    self._setup(**kwargs)

Attributes

xaml_source = 'GetValueWindow.xaml' class-attribute instance-attribute

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

default_title_key = 'pyRevit.DefaultWindowTitle' class-attribute instance-attribute

Title = title instance-attribute

Width = width instance-attribute

Height = height instance-attribute

response = None instance-attribute

Owner = owner instance-attribute

WindowStartupLocation = framework.Windows.WindowStartupLocation.CenterOwner instance-attribute

Functions

string_value_changed(sender, args)

Handle string vlaue update event.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def string_value_changed(self, sender, args):  # pylint: disable=unused-argument
    """Handle string vlaue update event."""
    filtered_rvalues = sorted(
        [x for x in self.reserved_values if self.stringValue_tb.Text == str(x)]
    )
    similar_rvalues = sorted(
        [x for x in self.reserved_values if self.stringValue_tb.Text in str(x)],
        reverse=True,
    )
    filtered_rvalues.extend(similar_rvalues)
    if filtered_rvalues:
        self.reservedValuesList.ItemsSource = filtered_rvalues
        self.show_element(self.reservedValuesListPanel)
        self.okayButton.IsEnabled = self.stringValue_tb.Text not in filtered_rvalues
    else:
        self.reservedValuesList.ItemsSource = []
        self.hide_element(self.reservedValuesListPanel)
        self.okayButton.IsEnabled = True

select(sender, args)

Process input data and set the response.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select(self, sender, args):  # pylint: disable=W0613
    """Process input data and set the response."""
    self.Close()
    if self.value_type == "string":
        self.response = self.stringValue_tb.Text
    elif self.value_type == "dropdown":
        self.response = self.dropdown_cb.SelectedItem
    elif self.value_type == "date":
        if self.datePicker.SelectedDate:
            selected = self.datePicker.SelectedDate
            self.response = datetime.datetime(
                selected.Year, selected.Month, selected.Day
            )
        else:
            self.response = None
    elif self.value_type == "slider":
        self.response = self.numberPicker.Value

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

handle_input_key(sender, args)

Handle keyboard input and close the window on Escape.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input and close the window on Escape."""
    if args.Key == Input.Key.Escape:
        self.Close()

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show(context, title=None, width=DEFAULT_INPUTWINDOW_WIDTH, height=DEFAULT_INPUTWINDOW_HEIGHT, **kwargs) classmethod

Show user input window.

Parameters:

Name	Type	Description	Default
context	any	window context element(s)	required
title	str	window title	None
width	int	window width	DEFAULT_INPUTWINDOW_WIDTH
height	int	window height	DEFAULT_INPUTWINDOW_HEIGHT
**kwargs	any	other arguments to be passed to window	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@classmethod
def show(
    cls,
    context,  # pylint: disable=W0221
    title=None,
    width=DEFAULT_INPUTWINDOW_WIDTH,
    height=DEFAULT_INPUTWINDOW_HEIGHT,
    **kwargs
):
    """Show user input window.

    Args:
        context (any): window context element(s)
        title (str): window title
        width (int): window width
        height (int): window height
        **kwargs (any): other arguments to be passed to window
    """
    dlg = cls(context, title, width, height, **kwargs)
    dlg.ShowDialog()
    return dlg.response

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

TemplatePromptBar(height=32, **kwargs)

Bases: WPFWindow

Template context-manager class for creating prompt bars.

Prompt bars are show at the top of the active Revit window and are designed for better prompt visibility.

Parameters:

Name	Type	Description	Default
height	int	window height	32
**kwargs	Any	other arguments to be passed to :func:_setup	{}

Initialize user prompt window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, height=32, **kwargs):
    """Initialize user prompt window."""
    WPFWindow.__init__(self, op.join(XAML_FILES_DIR, self.xaml_source))

    self.user_height = height
    self.update_window()
    self._setup(**kwargs)

Attributes

xaml_source = 'TemplatePromptBar.xaml' class-attribute instance-attribute

user_height = height instance-attribute

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

Functions

update_window()

Update the prompt bar to match Revit window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def update_window(self):
    """Update the prompt bar to match Revit window."""
    screen_area = HOST_APP.proc_screen_workarea
    scale_factor = 1.0 / HOST_APP.proc_screen_scalefactor
    top = left = width = height = 0

    window_rect = revit.ui.get_window_rectangle()

    # set width and height
    width = window_rect.Right - window_rect.Left
    height = self.user_height

    top = window_rect.Top
    # in maximized window, the top might be off the active screen
    # due to windows thicker window frames
    # lets cut the height and re-adjust the top
    top_diff = abs(screen_area.Top - top)
    if 10 > top_diff > 0 and top_diff < height:
        height -= top_diff
        top = screen_area.Top

    left = window_rect.Left
    # in maximized window, Left also might be off the active screen
    # due to windows thicker window frames
    # let's fix the width to accomodate the extra pixels as well
    left_diff = abs(screen_area.Left - left)
    if 10 > left_diff > 0 and left_diff < width:
        # deduct two times the left negative offset since this extra
        # offset happens on both left and right side
        width -= left_diff * 2
        left = screen_area.Left

    self.Top = top * scale_factor
    self.Left = left * scale_factor
    self.Width = width * scale_factor
    self.Height = height

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

handle_input_key(sender, args)

Handle keyboard input and close the window on Escape.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input and close the window on Escape."""
    if args.Key == Input.Key.Escape:
        self.Close()

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show(modal=False)

Show window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show(self, modal=False):
    """Show window."""
    if modal:
        return self.ShowDialog()
    # else open non-modal
    self.Show()

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

WarningBar(height=32, **kwargs)

Bases: TemplatePromptBar

Show warning bar at the top of Revit window.

Other Parameters:

Name	Type	Description
title	string	warning bar text
background	SolidColorBrush	background brush
foreground	SolidColorBrush	text brush

Examples:

with WarningBar(title='my warning'):
   # do stuff

Initialize user prompt window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, height=32, **kwargs):
    """Initialize user prompt window."""
    WPFWindow.__init__(self, op.join(XAML_FILES_DIR, self.xaml_source))

    self.user_height = height
    self.update_window()
    self._setup(**kwargs)

Attributes

xaml_source = 'WarningBar.xaml' class-attribute instance-attribute

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

user_height = height instance-attribute

Functions

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

handle_input_key(sender, args)

Handle keyboard input and close the window on Escape.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input and close the window on Escape."""
    if args.Key == Input.Key.Escape:
        self.Close()

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show(modal=False)

Show window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show(self, modal=False):
    """Show window."""
    if modal:
        return self.ShowDialog()
    # else open non-modal
    self.Show()

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

update_window()

Update the prompt bar to match Revit window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def update_window(self):
    """Update the prompt bar to match Revit window."""
    screen_area = HOST_APP.proc_screen_workarea
    scale_factor = 1.0 / HOST_APP.proc_screen_scalefactor
    top = left = width = height = 0

    window_rect = revit.ui.get_window_rectangle()

    # set width and height
    width = window_rect.Right - window_rect.Left
    height = self.user_height

    top = window_rect.Top
    # in maximized window, the top might be off the active screen
    # due to windows thicker window frames
    # lets cut the height and re-adjust the top
    top_diff = abs(screen_area.Top - top)
    if 10 > top_diff > 0 and top_diff < height:
        height -= top_diff
        top = screen_area.Top

    left = window_rect.Left
    # in maximized window, Left also might be off the active screen
    # due to windows thicker window frames
    # let's fix the width to accomodate the extra pixels as well
    left_diff = abs(screen_area.Left - left)
    if 10 > left_diff > 0 and left_diff < width:
        # deduct two times the left negative offset since this extra
        # offset happens on both left and right side
        width -= left_diff * 2
        left = screen_area.Left

    self.Top = top * scale_factor
    self.Left = left * scale_factor
    self.Width = width * scale_factor
    self.Height = height

ProgressBar(height=32, **kwargs)

Bases: TemplatePromptBar

Show progress bar at the top of Revit window.

Other Parameters:

Name	Type	Description
title	string	progress bar text, defaults to 0/100 progress format
indeterminate	bool	create indeterminate progress bar
cancellable	bool	add cancel button to progress bar
step	int	update progress intervals

Examples:

from pyrevit import forms
count = 1
with forms.ProgressBar(title='my command progress message') as pb:
   # do stuff
   pb.update_progress(count, 100)
   count += 1

Progress bar title could also be customized to show the current and total progress values. In example below, the progress bar message will be in format "0 of 100"

with forms.ProgressBar(title='{value} of {max_value}') as pb:

By default progress bar updates the progress every time the .update_progress method is called. For operations with a large number of max steps, the gui update process time will have a significate effect on the overall execution time of the command. In these cases, set the value of step argument to something larger than 1. In example below, the progress bar updates once per every 10 units of progress.

with forms.ProgressBar(title='message', steps=10):

Progress bar could also be set to indeterminate for operations of unknown length. In this case, the progress bar will show an infinitely running ribbon:

with forms.ProgressBar(title='message', indeterminate=True):

if cancellable is set on the object, a cancel button will show on the progress bar and .cancelled attribute will be set on the ProgressBar instance if users clicks on cancel button:

with forms.ProgressBar(title='message',
                       cancellable=True) as pb:
   # do stuff
   if pb.cancelled:
       # wrap up and cancel operation

Initialize user prompt window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, height=32, **kwargs):
    """Initialize user prompt window."""
    WPFWindow.__init__(self, op.join(XAML_FILES_DIR, self.xaml_source))

    self.user_height = height
    self.update_window()
    self._setup(**kwargs)

Attributes

xaml_source = 'ProgressBar.xaml' class-attribute instance-attribute

title property writable

Progress bar title.

indeterminate property writable

Progress bar indeterminate state.

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

user_height = height instance-attribute

Functions

clicked_cancel(sender, args)

Handler for cancel button clicked event.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def clicked_cancel(self, sender, args):  # pylint: disable=W0613
    """Handler for cancel button clicked event."""
    self.cancel_b.Content = "Cancelling..."
    self.cancelled = True  # pylint: disable=W0201

reset()

Reset progress value to 0.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def reset(self):
    """Reset progress value to 0."""
    self.update_progress(0, 1)

update_progress(new_value, max_value=1)

Update progress bar state with given min, max values.

Parameters:

Name	Type	Description	Default
new_value	float	current progress value	required
max_value	float	total progress value	1

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def update_progress(self, new_value, max_value=1):
    """Update progress bar state with given min, max values.

    Args:
        new_value (float): current progress value
        max_value (float): total progress value
    """
    self.max_value = max_value  # pylint: disable=W0201
    self.new_value = new_value  # pylint: disable=W0201
    if self.new_value == 0:
        self._dispatch_updater()
    elif self.step > 0:
        if self.new_value % self.step == 0:
            self._dispatch_updater()
    else:
        self._dispatch_updater()

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

handle_input_key(sender, args)

Handle keyboard input and close the window on Escape.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input and close the window on Escape."""
    if args.Key == Input.Key.Escape:
        self.Close()

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show(modal=False)

Show window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show(self, modal=False):
    """Show window."""
    if modal:
        return self.ShowDialog()
    # else open non-modal
    self.Show()

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

update_window()

Update the prompt bar to match Revit window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def update_window(self):
    """Update the prompt bar to match Revit window."""
    screen_area = HOST_APP.proc_screen_workarea
    scale_factor = 1.0 / HOST_APP.proc_screen_scalefactor
    top = left = width = height = 0

    window_rect = revit.ui.get_window_rectangle()

    # set width and height
    width = window_rect.Right - window_rect.Left
    height = self.user_height

    top = window_rect.Top
    # in maximized window, the top might be off the active screen
    # due to windows thicker window frames
    # lets cut the height and re-adjust the top
    top_diff = abs(screen_area.Top - top)
    if 10 > top_diff > 0 and top_diff < height:
        height -= top_diff
        top = screen_area.Top

    left = window_rect.Left
    # in maximized window, Left also might be off the active screen
    # due to windows thicker window frames
    # let's fix the width to accomodate the extra pixels as well
    left_diff = abs(screen_area.Left - left)
    if 10 > left_diff > 0 and left_diff < width:
        # deduct two times the left negative offset since this extra
        # offset happens on both left and right side
        width -= left_diff * 2
        left = screen_area.Left

    self.Top = top * scale_factor
    self.Left = left * scale_factor
    self.Width = width * scale_factor
    self.Height = height

SearchPrompt(search_db, width, height, **kwargs)

Bases: WPFWindow

Standard prompt for pyRevit search.

Parameters:

Name	Type	Description	Default
search_db	list	list of possible search targets	required
width	int	width of search prompt window	required
height	int	height of search prompt window	required

Other Parameters:

Name	Type	Description
search_tip	str	text to show in grayscale when search box is empty
switches	str	list of switches

Returns:

Type	Description
tuple[str, dict] | str	matched string if switches are not provided, matched strings, and dict of switches otherwise.

Examples:

from pyrevit import forms
# assume search input of '/switch1 target1'
matched_str, args, switches = forms.SearchPrompt.show(
    search_db=['target1', 'target2', 'target3', 'target4'],
    switches=['/switch1', '/switch2'],
    search_tip='pyRevit Search'
    )
matched_str
'target1'
args
['--help', '--branch', 'branchname']
switches
{'/switch1': True, '/switch2': False}

Initialize search prompt window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, search_db, width, height, **kwargs):
    """Initialize search prompt window."""
    WPFWindow.__init__(self, op.join(XAML_FILES_DIR, "SearchPrompt.xaml"))
    self.Width = width
    self.MinWidth = self.Width
    self.Height = height

    self.search_tip = kwargs.get("search_tip", "")

    if isinstance(search_db, list):
        self._search_db = None
        self._search_db_keys = search_db
    elif isinstance(search_db, dict):
        self._search_db = search_db
        self._search_db_keys = sorted(self._search_db.keys())
    else:
        raise PyRevitException("Unknown search database type")

    self._search_res = None
    self._switches = kwargs.get("switches", [])
    self._setup_response()

    self.search_tb.Focus()
    self.hide_element(self.tab_icon)
    self.hide_element(self.return_icon)
    self.search_tb.Text = ""
    self.set_search_results()

Attributes

Width = width instance-attribute

MinWidth = self.Width instance-attribute

Height = height instance-attribute

search_tip = kwargs.get('search_tip', '') instance-attribute

search_input property writable

Current search input.

search_input_parts property

Current cleaned up search term.

search_term property

Current cleaned up search term.

search_term_switches property

Find matching switches in search term.

search_term_args property

Find arguments in search term.

search_term_main property

Current cleaned up search term without the listed switches.

search_matches property

List of matches for the given search term.

pyrevit_version property

Active pyRevit formatted version string, e.g. '4.9-beta'.

Functions

update_results_display(fill_match=False)

Update search prompt results based on current input text.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def update_results_display(self, fill_match=False):
    """Update search prompt results based on current input text."""
    self.directmatch_tb.Text = ""
    self.wordsmatch_tb.Text = ""

    results = self.search_matches
    res_cout = len(results)

    mlogger.debug("unique results count: %s", res_cout)
    mlogger.debug("unique results: %s", results)

    if res_cout > 1:
        self.show_element(self.tab_icon)
        self.hide_element(self.return_icon)
    elif res_cout == 1:
        self.hide_element(self.tab_icon)
        self.show_element(self.return_icon)
    else:
        self.hide_element(self.tab_icon)
        self.hide_element(self.return_icon)

    if self._result_index >= res_cout:
        self._result_index = 0  # pylint: disable=W0201

    if self._result_index < 0:
        self._result_index = res_cout - 1  # pylint: disable=W0201

    if not self.search_input:
        self.directmatch_tb.Text = self.search_tip
        return

    if results:
        input_term = self.search_term
        cur_res = results[self._result_index]
        mlogger.debug("current result: %s", cur_res)
        if fill_match:
            self.search_input = cur_res
        else:
            if cur_res.lower().startswith(input_term):
                self.directmatch_tb.Text = (
                    self.search_input + cur_res[len(input_term) :]
                )
                mlogger.debug("directmatch_tb.Text: %s", self.directmatch_tb.Text)
            else:
                self.wordsmatch_tb.Text = "- {}".format(cur_res)
                mlogger.debug("wordsmatch_tb.Text: %s", self.wordsmatch_tb.Text)
        tooltip = self._search_db.get(cur_res, None)
        if tooltip:
            self.tooltip_tb.Text = tooltip
            self.show_element(self.tooltip_tb)
        else:
            self.hide_element(self.tooltip_tb)
        self._search_res = cur_res
        return True
    return False

set_search_results(*args)

Set search results for returning.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_search_results(self, *args):
    """Set search results for returning."""
    self._result_index = 0
    self._search_results = []

    mlogger.debug("search input: %s", self.search_input)
    mlogger.debug("search term: %s", self.search_term)
    mlogger.debug("search term (main): %s", self.search_term_main)
    mlogger.debug("search term (parts): %s", self.search_input_parts)
    mlogger.debug("search term (args): %s", self.search_term_args)
    mlogger.debug("search term (switches): %s", self.search_term_switches)

    for resultset in args:
        mlogger.debug("result set: %s}", resultset)
        self._search_results.extend(sorted(resultset))

    mlogger.debug("results: %s", self._search_results)

find_direct_match(input_text)

Find direct text matches in search term.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def find_direct_match(self, input_text):
    """Find direct text matches in search term."""
    results = []
    if input_text:
        for cmd_name in self._search_db_keys:
            if cmd_name.lower().startswith(input_text):
                results.append(cmd_name)

    return results

find_word_match(input_text)

Find direct word matches in search term.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def find_word_match(self, input_text):
    """Find direct word matches in search term."""
    results = []
    if input_text:
        cur_words = input_text.split(" ")
        for cmd_name in self._search_db_keys:
            if all([x in cmd_name.lower() for x in cur_words]):
                results.append(cmd_name)

    return results

search_txt_changed(sender, args)

Handle text changed event.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def search_txt_changed(self, sender, args):  # pylint: disable=W0613
    """Handle text changed event."""
    input_term = self.search_term_main
    dmresults = self.find_direct_match(input_term)
    wordresults = self.find_word_match(input_term)
    self.set_search_results(dmresults, wordresults)
    self.update_results_display()

handle_kb_key(sender, args)

Handle keyboard input event.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_kb_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input event."""
    shiftdown = Input.Keyboard.IsKeyDown(
        Input.Key.LeftShift
    ) or Input.Keyboard.IsKeyDown(Input.Key.RightShift)
    # Escape: set response to none and close
    if args.Key == Input.Key.Escape:
        self._setup_response()
        self.Close()
    # Enter: close, returns matched response automatically
    elif args.Key == Input.Key.Enter:
        if self.search_tb.Text != "":
            self._setup_response(response=self._search_res)
            args.Handled = True
            self.Close()
    # Shift+Tab, Tab: Cycle through matches
    elif args.Key == Input.Key.Tab and shiftdown:
        self._result_index -= 1
        self.update_results_display()
    elif args.Key == Input.Key.Tab:
        self._result_index += 1
        self.update_results_display()
    # Up, Down: Cycle through matches
    elif args.Key == Input.Key.Up:
        self._result_index -= 1
        self.update_results_display()
    elif args.Key == Input.Key.Down:
        self._result_index += 1
        self.update_results_display()
    # Right, End: Autocomplete with displayed match
    elif args.Key in [Input.Key.Right, Input.Key.End]:
        self.update_results_display(fill_match=True)

show(search_db, width=DEFAULT_SEARCHWND_WIDTH, height=DEFAULT_SEARCHWND_HEIGHT, **kwargs) classmethod

Show search prompt.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@classmethod
def show(
    cls,
    search_db,  # pylint: disable=W0221
    width=DEFAULT_SEARCHWND_WIDTH,
    height=DEFAULT_SEARCHWND_HEIGHT,
    **kwargs
):
    """Show search prompt."""
    dlg = cls(search_db, width, height, **kwargs)
    dlg.ShowDialog()
    return dlg.response

setup_resources(wpf_ctrl) staticmethod

Set pyRevit colour resources on any WPF control.

Parameters:

Name	Type	Description	Default
wpf_ctrl		any WPF FrameworkElement with a Resources dict.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def setup_resources(wpf_ctrl):
    """Set pyRevit colour resources on any WPF control.

    Args:
        wpf_ctrl: any WPF FrameworkElement with a Resources dict.
    """
    wpf_ctrl.Resources["pyRevitDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x2C, 0x3E, 0x50
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkColor"] = Media.Color.FromArgb(
        0xFF, 0x23, 0x30, 0x3D
    )
    wpf_ctrl.Resources["pyRevitButtonColor"] = Media.Color.FromArgb(
        0xFF, 0xFF, 0xFF, 0xFF
    )
    wpf_ctrl.Resources["pyRevitAccentColor"] = Media.Color.FromArgb(
        0xFF, 0xF3, 0x9C, 0x12
    )
    wpf_ctrl.Resources["pyRevitDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitAccentBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitAccentColor"]
    )
    wpf_ctrl.Resources["pyRevitDarkerDarkBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitDarkerDarkColor"]
    )
    wpf_ctrl.Resources["pyRevitButtonForgroundBrush"] = Media.SolidColorBrush(
        wpf_ctrl.Resources["pyRevitButtonColor"]
    )
    wpf_ctrl.Resources["pyRevitRecognizesAccessKey"] = DEFAULT_RECOGNIZE_ACCESS_KEY

merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file into this control's resources.

Parameters:

Name	Type	Description	Default
xaml_source	str	absolute path to a ResourceDictionary xaml file.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file into this control's resources.

    Args:
        xaml_source (str): absolute path to a ResourceDictionary xaml file.
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)

get_locale_string(string_name)

Return a localised string from the merged ResourceDictionary.

Parameters:

Name	Type	Description	Default
string_name	str	resource key.	required

Returns:

Name	Type	Description
str		localised string value.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_locale_string(self, string_name):
    """Return a localised string from the merged ResourceDictionary.

    Args:
        string_name (str): resource key.

    Returns:
        str: localised string value.
    """
    return self.FindResource(string_name)

set_image_source_file(wpf_element, image_file) staticmethod

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    if not op.exists(image_file):
        wpf_element.Source = utils.bitmap_from_file(
            os.path.join(EXEC_PARAMS.command_path, image_file)
        )
    else:
        wpf_element.Source = utils.bitmap_from_file(image_file)

set_image_source(wpf_element, image_file)

Set the source of a WPF Image element from a file path.

Parameters:

Name	Type	Description	Default
wpf_element	Image	target image element.	required
image_file	str	absolute or command-relative image path.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_image_source(self, wpf_element, image_file):
    """Set the source of a WPF Image element from a file path.

    Args:
        wpf_element (System.Windows.Controls.Image): target image element.
        image_file (str): absolute or command-relative image path.
    """
    _WPFMixin.set_image_source_file(wpf_element, image_file)

hide_element(*wpf_elements) staticmethod

Collapse one or more WPF elements (removes from layout).

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to collapse.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def hide_element(*wpf_elements):
    """Collapse one or more WPF elements (removes from layout).

    Args:
        *wpf_elements (list[UIElement]): elements to collapse.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED

show_element(*wpf_elements) staticmethod

Make one or more collapsed WPF elements visible.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to show.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def show_element(*wpf_elements):
    """Make one or more collapsed WPF elements visible.

    Args:
        *wpf_elements (list[UIElement]): elements to show.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE

toggle_element(*wpf_elements) staticmethod

Toggle visibility of one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to toggle.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to toggle.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            _WPFMixin.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            _WPFMixin.show_element(wpfel)

disable_element(*wpf_elements) staticmethod

Disable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to disable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def disable_element(*wpf_elements):
    """Disable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to disable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False

enable_element(*wpf_elements) staticmethod

Enable one or more WPF elements.

Parameters:

Name	Type	Description	Default
*wpf_elements	list[UIElement]	elements to enable.	()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@staticmethod
def enable_element(*wpf_elements):
    """Enable one or more WPF elements.

    Args:
        *wpf_elements (list[UIElement]): elements to enable.
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True

dispatch(func, *args, **kwargs)

Run a function on the opposite thread.

When called from the UI thread, spawns a background thread. When called from a background thread, marshals execution back onto the UI thread via the Dispatcher. This makes the pattern for background work + UI updates symmetrical:

# on UI thread — starts background work
self.dispatch(self._do_work)

def _do_work(self):
    ...heavy work...
    # on background thread — posts UI update
    self.dispatch(self._update_label, "done")

Parameters:

Name	Type	Description	Default
func	Callable	function to run.	required
*args		positional arguments forwarded to func.	()
**kwargs		keyword arguments forwarded to func.	{}

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def dispatch(self, func, *args, **kwargs):
    """Run a function on the opposite thread.

    When called from the UI thread, spawns a background thread.
    When called from a background thread, marshals execution back
    onto the UI thread via the Dispatcher.  This makes the pattern
    for background work + UI updates symmetrical:

        # on UI thread — starts background work
        self.dispatch(self._do_work)

        def _do_work(self):
            ...heavy work...
            # on background thread — posts UI update
            self.dispatch(self._update_label, "done")

    Args:
        func (Callable): function to run.
        *args: positional arguments forwarded to func.
        **kwargs: keyword arguments forwarded to func.
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(target=func, args=args, kwargs=kwargs)
        t.start()
    else:
        self.Dispatcher.Invoke(
            System.Action(lambda: func(*args, **kwargs)),
            Threading.DispatcherPriority.Background,
        )

handle_url_click(sender, args)

XAML event handler: open a Hyperlink URL in the default browser.

Wire up in XAML with: RequestNavigate="handle_url_click"

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_url_click(self, sender, args):  # pylint: disable=unused-argument
    """XAML event handler: open a Hyperlink URL in the default browser.

    Wire up in XAML with:  RequestNavigate="handle_url_click"
    """
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

load_xaml(xaml_source, literal_string=False, handle_esc=True, set_owner=True)

Load the window XAML file.

Parameters:

Name	Type	Description	Default
xaml_source	str	The XAML content or file path to load.	required
literal_string	bool	True if xaml_source is content, False if it is a path. Defaults to False.	False
handle_esc	bool	Whether the ESC key should be handled. Defaults to True.	True
set_owner	bool	Whether to set the window owner. Defaults to True.	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def load_xaml(
    self, xaml_source, literal_string=False, handle_esc=True, set_owner=True
):
    """Load the window XAML file.

    Args:
        xaml_source (str): The XAML content or file path to load.
        literal_string (bool, optional): True if `xaml_source` is content,
            False if it is a path. Defaults to False.
        handle_esc (bool, optional): Whether the ESC key should be handled.
            Defaults to True.
        set_owner (bool, optional): Whether to set the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    _WPFMixin.setup_resources(self)
    if not literal_string:
        xaml_path, pending_resource_merge = _resolve_xaml_source(xaml_source)
        # merge before LoadComponent so resources are available during parse
        if pending_resource_merge:
            self.merge_resource_dict(pending_resource_merge)
        wpf.LoadComponent(self, xaml_path)
    else:
        wpf.LoadComponent(self, framework.StringReader(xaml_source))

    # set properties
    self.thread_id = framework.get_current_thread_id()
    if set_owner:
        self.setup_owner()
    self.setup_icon()
    if handle_esc:
        self.setup_default_handlers()

setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow

setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_default_handlers(self):
    """Set the default handlers."""
    self.PreviewKeyDown += self.handle_input_key  # pylint: disable=E1101

handle_input_key(sender, args)

Handle keyboard input and close the window on Escape.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def handle_input_key(self, sender, args):  # pylint: disable=W0613
    """Handle keyboard input and close the window on Escape."""
    if args.Key == Input.Key.Escape:
        self.Close()

set_icon(icon_path)

Set window icon to given icon path.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def set_icon(self, icon_path):
    """Set window icon to given icon path."""
    self.Icon = utils.bitmap_from_file(icon_path)

setup_icon()

Setup default window icon.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def setup_icon(self):
    """Setup default window icon."""
    self.set_icon(op.join(BIN_DIR, "pyrevit_settings.png"))

hide()

Hide window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def hide(self):
    """Hide window."""
    self.Hide()

show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()

conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def conceal(self):
    """Conceal window."""
    return WindowToggler(self)

RevisionOption(revision_element)

Bases: TemplateListItem

Revision wrapper for :func:select_revisions.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, revision_element):
    super(RevisionOption, self).__init__(revision_element)

Attributes

name property

Revision name (description).

item = orig_item instance-attribute

state = checked instance-attribute

checkable property writable

List Item CheckBox Visibility.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def add_PropertyChanged(self, value):
    """Called when a property is added to the object."""
    self.PropertyChanged += value

remove_PropertyChanged(value)

Called when a property is removed from the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def remove_PropertyChanged(self, value):
    """Called when a property is removed from the object."""
    self.PropertyChanged -= value

OnPropertyChanged(prop_name)

Called when a property is changed.

Parameters:

Name	Type	Description	Default
prop_name	str	property name	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def OnPropertyChanged(self, prop_name):
    """Called when a property is changed.

    Args:
        prop_name (str): property name
    """
    if self._propertyChangedCaller:
        args = ComponentModel.PropertyChangedEventArgs(prop_name)
        self._propertyChangedCaller(self, args)

unwrap()

Unwrap and return wrapped object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item

checked(value)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@checked.setter
def checked(self, value):
    self.state = value

SheetOption(sheet_element)

Bases: TemplateListItem

Sheet wrapper for :func:select_sheets.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, sheet_element):
    super(SheetOption, self).__init__(sheet_element)

Attributes

name property

Sheet name.

number property

Sheet number.

item = orig_item instance-attribute

state = checked instance-attribute

checkable property writable

List Item CheckBox Visibility.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def add_PropertyChanged(self, value):
    """Called when a property is added to the object."""
    self.PropertyChanged += value

remove_PropertyChanged(value)

Called when a property is removed from the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def remove_PropertyChanged(self, value):
    """Called when a property is removed from the object."""
    self.PropertyChanged -= value

OnPropertyChanged(prop_name)

Called when a property is changed.

Parameters:

Name	Type	Description	Default
prop_name	str	property name	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def OnPropertyChanged(self, prop_name):
    """Called when a property is changed.

    Args:
        prop_name (str): property name
    """
    if self._propertyChangedCaller:
        args = ComponentModel.PropertyChangedEventArgs(prop_name)
        self._propertyChangedCaller(self, args)

unwrap()

Unwrap and return wrapped object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item

checked(value)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@checked.setter
def checked(self, value):
    self.state = value

ViewOption(view_element)

Bases: TemplateListItem

View wrapper for :func:select_views.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, view_element):
    super(ViewOption, self).__init__(view_element)

Attributes

name property

View name.

item = orig_item instance-attribute

state = checked instance-attribute

checkable property writable

List Item CheckBox Visibility.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def add_PropertyChanged(self, value):
    """Called when a property is added to the object."""
    self.PropertyChanged += value

remove_PropertyChanged(value)

Called when a property is removed from the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def remove_PropertyChanged(self, value):
    """Called when a property is removed from the object."""
    self.PropertyChanged -= value

OnPropertyChanged(prop_name)

Called when a property is changed.

Parameters:

Name	Type	Description	Default
prop_name	str	property name	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def OnPropertyChanged(self, prop_name):
    """Called when a property is changed.

    Args:
        prop_name (str): property name
    """
    if self._propertyChangedCaller:
        args = ComponentModel.PropertyChangedEventArgs(prop_name)
        self._propertyChangedCaller(self, args)

unwrap()

Unwrap and return wrapped object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item

checked(value)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@checked.setter
def checked(self, value):
    self.state = value

LevelOption(level_element)

Bases: TemplateListItem

Level wrapper for :func:select_levels.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, level_element):
    super(LevelOption, self).__init__(level_element)

Attributes

name property

Level name.

item = orig_item instance-attribute

state = checked instance-attribute

checkable property writable

List Item CheckBox Visibility.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def add_PropertyChanged(self, value):
    """Called when a property is added to the object."""
    self.PropertyChanged += value

remove_PropertyChanged(value)

Called when a property is removed from the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def remove_PropertyChanged(self, value):
    """Called when a property is removed from the object."""
    self.PropertyChanged -= value

OnPropertyChanged(prop_name)

Called when a property is changed.

Parameters:

Name	Type	Description	Default
prop_name	str	property name	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def OnPropertyChanged(self, prop_name):
    """Called when a property is changed.

    Args:
        prop_name (str): property name
    """
    if self._propertyChangedCaller:
        args = ComponentModel.PropertyChangedEventArgs(prop_name)
        self._propertyChangedCaller(self, args)

unwrap()

Unwrap and return wrapped object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item

checked(value)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@checked.setter
def checked(self, value):
    self.state = value

FamilyParamOption(fparam, builtin=False, labeled=False, associated=False)

Bases: TemplateListItem

Level wrapper for :func:select_family_parameters.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def __init__(self, fparam, builtin=False, labeled=False, associated=False):
    super(FamilyParamOption, self).__init__(fparam)
    self.isbuiltin = builtin
    self.islabeled = labeled
    self.isassociated = associated

Attributes

isbuiltin = builtin instance-attribute

islabeled = labeled instance-attribute

isassociated = associated instance-attribute

name property

Family Parameter name.

istype property

Is type parameter.

item = orig_item instance-attribute

state = checked instance-attribute

checkable property writable

List Item CheckBox Visibility.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def add_PropertyChanged(self, value):
    """Called when a property is added to the object."""
    self.PropertyChanged += value

remove_PropertyChanged(value)

Called when a property is removed from the object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def remove_PropertyChanged(self, value):
    """Called when a property is removed from the object."""
    self.PropertyChanged -= value

OnPropertyChanged(prop_name)

Called when a property is changed.

Parameters:

Name	Type	Description	Default
prop_name	str	property name	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def OnPropertyChanged(self, prop_name):
    """Called when a property is changed.

    Args:
        prop_name (str): property name
    """
    if self._propertyChangedCaller:
        args = ComponentModel.PropertyChangedEventArgs(prop_name)
        self._propertyChangedCaller(self, args)

unwrap()

Unwrap and return wrapped object.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item

checked(value)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

@checked.setter
def checked(self, value):
    self.state = value

Functions

is_registered_dockable_panel(panel_type)

Check if dockable panel is already registered.

Parameters:

Name	Type	Description	Default
panel_type	WPFPanel	dockable panel type	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def is_registered_dockable_panel(panel_type):
    """Check if dockable panel is already registered.

    Args:
        panel_type (forms.WPFPanel): dockable panel type
    """
    panel_uuid = coreutils.Guid.Parse(panel_type.panel_id)
    dockable_panel_id = UI.DockablePaneId(panel_uuid)
    return UI.DockablePane.PaneIsRegistered(dockable_panel_id)

register_dockable_panel(panel_type, default_visible=True)

Register a dockable panel with Revit and return its instance.

This function creates a provider for the given panel type, registers the corresponding dockable pane with Revit, and returns the live WPF panel instance managed by that provider.

Parameters:

Name	Type	Description	Default
panel_type	WPFPanel	dockable panel type	required
default_visible	bool	Whether the panel should be visible by default when registered.	True

Returns:

Type	Description
	forms.WPFPanel: The live panel instance created during registration.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def register_dockable_panel(panel_type, default_visible=True):
    """Register a dockable panel with Revit and return its instance.

    This function creates a provider for the given panel type, registers the
    corresponding dockable pane with Revit, and returns the live WPF panel
    instance managed by that provider.

    Args:
        panel_type (forms.WPFPanel): dockable panel type
        default_visible (bool, optional):
            Whether the panel should be visible by default when registered.

    Returns:
        forms.WPFPanel: The live panel instance created during registration.
    """
    if not isinstance(panel_type, type) or not issubclass(panel_type, WPFPanel):
        raise PyRevitException("Dockable pane must be a subclass of forms.WPFPanel")

    try:
        panel_uuid = coreutils.Guid.Parse(panel_type.panel_id)
    except System.FormatException:
        raise PyRevitException(
            'Invalid dockable panel id "{}"'.format(panel_type.panel_id)
        )
    dockable_panel_id = UI.DockablePaneId(panel_uuid)
    panel_provider = _WPFPanelProvider(panel_type, default_visible)
    HOST_APP.uiapp.RegisterDockablePane(
        dockable_panel_id, panel_type.panel_title, panel_provider
    )

    return panel_provider.panel

get_dockable_panel(panel_type_or_id)

Retrieve the Revit dockable pane handle for a registered panel.

Parameters:

Name	Type	Description	Default
panel_type_or_id	WPFPanel | str	dockable panel type (subclass of forms.WPFPanel) or panel id string corresponding to the Revit dockable pane id.	required

Returns:

Type	Description
	UI.DockablePane: the live panel pane handle.

Raises:

Type	Description
PyRevitException	if the panel id is not registered with Revit.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def get_dockable_panel(panel_type_or_id):
    """Retrieve the Revit dockable pane handle for a registered panel.

    Args:
        panel_type_or_id (forms.WPFPanel | str):
            dockable panel type (subclass of forms.WPFPanel) or panel id string
            corresponding to the Revit dockable pane id.

    Returns:
        UI.DockablePane: the live panel pane handle.

    Raises:
        PyRevitException: if the panel id is not registered with Revit.
    """
    dpanel_id = None
    if isinstance(panel_type_or_id, str):
        try:
            panel_id = coreutils.Guid.Parse(panel_type_or_id)
        except System.FormatException:
            raise PyRevitException(
                'Invalid dockable panel id "{}"'.format(panel_type_or_id)
            )
        dpanel_id = UI.DockablePaneId(panel_id)
    elif isinstance(panel_type_or_id, type) and issubclass(panel_type_or_id, WPFPanel):
        try:
            panel_id = coreutils.Guid.Parse(panel_type_or_id.panel_id)
        except System.FormatException:
            raise PyRevitException(
                'Invalid dockable panel id "{}"'.format(panel_type_or_id.panel_id)
            )
        dpanel_id = UI.DockablePaneId(panel_id)
    else:
        raise PyRevitException("Given type is not a forms.WPFPanel")

    if dpanel_id:
        if UI.DockablePane.PaneIsRegistered(dpanel_id):
            dockable_panel = HOST_APP.uiapp.GetDockablePane(dpanel_id)
            return dockable_panel
        else:
            raise PyRevitException(
                'Panel with id "%s" is not registered' % panel_type_or_id
            )

open_dockable_panel(panel_type_or_id)

Open previously registered dockable panel.

Parameters:

Name	Type	Description	Default
panel_type_or_id	WPFPanel | str	panel type or id	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def open_dockable_panel(panel_type_or_id):
    """Open previously registered dockable panel.

    Args:
        panel_type_or_id (forms.WPFPanel | str): panel type or id
    """
    toggle_dockable_panel(panel_type_or_id, True)

close_dockable_panel(panel_type_or_id)

Close previously registered dockable panel.

Parameters:

Name	Type	Description	Default
panel_type_or_id	WPFPanel | str	panel type or id	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def close_dockable_panel(panel_type_or_id):
    """Close previously registered dockable panel.

    Args:
        panel_type_or_id (forms.WPFPanel | str): panel type or id
    """
    toggle_dockable_panel(panel_type_or_id, False)

toggle_dockable_panel(panel_type_or_id, state)

Toggle previously registered dockable panel.

Parameters:

Name	Type	Description	Default
panel_type_or_id	WPFPanel | str	panel type or id	required
state	bool	True to show the panel, False to hide it.	required

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def toggle_dockable_panel(panel_type_or_id, state):
    """Toggle previously registered dockable panel.

    Args:
        panel_type_or_id (forms.WPFPanel | str): panel type or id
        state (bool): True to show the panel, False to hide it.
    """
    dockable_panel = get_dockable_panel(panel_type_or_id)
    if state:
        dockable_panel.Show()
    else:
        dockable_panel.Hide()

select_revisions(title='Select Revision', button_name='Select', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=True, filterfunc=None, doc=None)

Standard form for selecting revisions.

Parameters:

Name	Type	Description	Default
title	str	list window title	'Select Revision'
button_name	str	list window button caption	'Select'
width	int	width of list window	DEFAULT_INPUTWINDOW_WIDTH
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
filterfunc	function	filter function to be applied to context items.	None
doc	Document	source document for revisions; defaults to active document	None

Returns:

Type	Description
list[Revision]	list of selected revisions

Examples:

from pyrevit import forms
forms.select_revisions()
[<Autodesk.Revit.DB.Revision object>,
 <Autodesk.Revit.DB.Revision object>]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_revisions(
    title="Select Revision",
    button_name="Select",
    width=DEFAULT_INPUTWINDOW_WIDTH,
    multiple=True,
    filterfunc=None,
    doc=None,
):
    """Standard form for selecting revisions.

    Args:
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        width (int, optional): width of list window
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        filterfunc (function):
            filter function to be applied to context items.
        doc (DB.Document, optional):
            source document for revisions; defaults to active document

    Returns:
        (list[DB.Revision]): list of selected revisions

    Examples:
        ```python
        from pyrevit import forms
        forms.select_revisions()
        [<Autodesk.Revit.DB.Revision object>,
         <Autodesk.Revit.DB.Revision object>]
        ```
    """
    doc = doc or DOCS.doc
    revisions = sorted(
        revit.query.get_revisions(doc=doc), key=lambda x: x.SequenceNumber
    )

    if filterfunc:
        revisions = filter(filterfunc, revisions)

    # ask user for revisions
    selected_revs = SelectFromList.show(
        [RevisionOption(x) for x in revisions],
        title=title,
        button_name=button_name,
        width=width,
        multiselect=multiple,
        checked_only=True,
    )

    return selected_revs

select_sheets(title='Select Sheets', button_name='Select', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=True, filterfunc=None, doc=None, include_placeholder=True, use_selection=False)

Standard form for selecting sheets.

Sheets are grouped into sheet sets and sheet set can be selected from a drop down box at the top of window.

Parameters:

Name	Type	Description	Default
title	str	list window title	'Select Sheets'
button_name	str	list window button caption	'Select'
width	int	width of list window	DEFAULT_INPUTWINDOW_WIDTH
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
filterfunc	function	filter function to be applied to context items.	None
doc	Document	source document for sheets; defaults to active document	None
include_placeholder	bool	include a placeholder. Defaults to True	True
use_selection	bool	ask if user wants to use currently selected sheets.	False

Returns:

Type	Description
list[ViewSheet]	list of selected sheets

Examples:

from pyrevit import forms
forms.select_sheets()
[<Autodesk.Revit.DB.ViewSheet object>,
 <Autodesk.Revit.DB.ViewSheet object>]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_sheets(
    title="Select Sheets",
    button_name="Select",
    width=DEFAULT_INPUTWINDOW_WIDTH,
    multiple=True,
    filterfunc=None,
    doc=None,
    include_placeholder=True,
    use_selection=False,
):
    """Standard form for selecting sheets.

    Sheets are grouped into sheet sets and sheet set can be selected from
    a drop down box at the top of window.

    Args:
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        width (int, optional): width of list window
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        filterfunc (function):
            filter function to be applied to context items.
        doc (DB.Document, optional):
            source document for sheets; defaults to active document
        include_placeholder (bool, optional): include a placeholder.
            Defaults to True
        use_selection (bool, optional):
            ask if user wants to use currently selected sheets.

    Returns:
        (list[DB.ViewSheet]): list of selected sheets

    Examples:
        ```python
        from pyrevit import forms
        forms.select_sheets()
        [<Autodesk.Revit.DB.ViewSheet object>,
         <Autodesk.Revit.DB.ViewSheet object>]
        ```
    """
    doc = doc or DOCS.doc

    # check for previously selected sheets
    if use_selection:
        current_selected_sheets = revit.get_selection().include(DB.ViewSheet).elements
        if filterfunc:
            current_selected_sheets = filter(filterfunc, current_selected_sheets)

        if not include_placeholder:
            current_selected_sheets = [
                x for x in current_selected_sheets if not x.IsPlaceholder
            ]

        if current_selected_sheets and ask_to_use_selected(
            "sheets", count=len(current_selected_sheets), multiple=multiple
        ):
            return current_selected_sheets if multiple else current_selected_sheets[0]

    # otherwise get all sheets and prompt for selection
    all_ops = {}
    all_sheets = (
        DB.FilteredElementCollector(doc)
        .OfClass(DB.ViewSheet)
        .WhereElementIsNotElementType()
        .ToElements()
    )

    if filterfunc:
        all_sheets = filter(filterfunc, all_sheets)

    if not include_placeholder:
        all_sheets = [x for x in all_sheets if not x.IsPlaceholder]

    all_sheets_ops = sorted(
        [SheetOption(x) for x in all_sheets], key=lambda x: x.number
    )
    all_ops["All Sheets"] = all_sheets_ops

    sheetsets = revit.query.get_sheet_sets(doc)
    for sheetset in sheetsets:
        sheetset_sheets = [x for x in sheetset.Views if isinstance(x, DB.ViewSheet)]
        if filterfunc:
            sheetset_sheets = filter(filterfunc, sheetset_sheets)
        sheetset_ops = sorted(
            [SheetOption(x) for x in sheetset_sheets], key=lambda x: x.number
        )
        if sheetset.Name == "All Sheets":
            all_ops["[" + sheetset.Name + "]"] = sheetset_ops
        else:
            all_ops[sheetset.Name] = sheetset_ops

    # ask user for multiple sheets
    selected_sheets = SelectFromList.show(
        all_ops,
        title=title,
        group_selector_title="Sheet Sets:",
        button_name=button_name,
        width=width,
        multiselect=multiple,
        checked_only=True,
        default_group="All Sheets",
    )

    return selected_sheets

select_views(title='Select Views', button_name='Select', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=True, filterfunc=None, doc=None, use_selection=False)

Standard form for selecting views.

Parameters:

Name	Type	Description	Default
title	str	list window title	'Select Views'
button_name	str	list window button caption	'Select'
width	int	width of list window	DEFAULT_INPUTWINDOW_WIDTH
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
filterfunc	function	filter function to be applied to context items.	None
doc	Document	source document for views; defaults to active document	None
use_selection	bool	ask if user wants to use currently selected views.	False

Returns:

Type	Description
list[View]	list of selected views

Examples:

from pyrevit import forms
forms.select_views()
[<Autodesk.Revit.DB.View object>,
 <Autodesk.Revit.DB.View object>]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_views(
    title="Select Views",
    button_name="Select",
    width=DEFAULT_INPUTWINDOW_WIDTH,
    multiple=True,
    filterfunc=None,
    doc=None,
    use_selection=False,
):
    """Standard form for selecting views.

    Args:
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        width (int, optional): width of list window
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        filterfunc (function):
            filter function to be applied to context items.
        doc (DB.Document, optional):
            source document for views; defaults to active document
        use_selection (bool, optional):
            ask if user wants to use currently selected views.

    Returns:
        (list[DB.View]): list of selected views

    Examples:
        ```python
        from pyrevit import forms
        forms.select_views()
        [<Autodesk.Revit.DB.View object>,
         <Autodesk.Revit.DB.View object>]
        ```
    """
    doc = doc or DOCS.doc

    # check for previously selected sheets
    if use_selection:
        current_selected_views = revit.get_selection().include(DB.View).elements
        if filterfunc:
            current_selected_views = filter(filterfunc, current_selected_views)

        if current_selected_views and ask_to_use_selected(
            "views", count=len(current_selected_views), multiple=multiple
        ):
            return current_selected_views if multiple else current_selected_views[0]

    # otherwise get all sheets and prompt for selection
    all_graphviews = revit.query.get_all_views(doc=doc)

    if filterfunc:
        all_graphviews = filter(filterfunc, all_graphviews)

    selected_views = SelectFromList.show(
        sorted([ViewOption(x) for x in all_graphviews], key=lambda x: x.name),
        title=title,
        button_name=button_name,
        width=width,
        multiselect=multiple,
        checked_only=True,
    )

    return selected_views

select_levels(title='Select Levels', button_name='Select', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=True, filterfunc=None, doc=None, use_selection=False)

Standard form for selecting levels.

Parameters:

Name	Type	Description	Default
title	str	list window title	'Select Levels'
button_name	str	list window button caption	'Select'
width	int	width of list window	DEFAULT_INPUTWINDOW_WIDTH
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
filterfunc	function	filter function to be applied to context items.	None
doc	Document	source document for levels; defaults to active document	None
use_selection	bool	ask if user wants to use currently selected levels.	False

Returns:

Type	Description
list[Level]	list of selected levels

Examples:

from pyrevit import forms
forms.select_levels()
[<Autodesk.Revit.DB.Level object>,
 <Autodesk.Revit.DB.Level object>]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_levels(
    title="Select Levels",
    button_name="Select",
    width=DEFAULT_INPUTWINDOW_WIDTH,
    multiple=True,
    filterfunc=None,
    doc=None,
    use_selection=False,
):
    """Standard form for selecting levels.

    Args:
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        width (int, optional): width of list window
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        filterfunc (function):
            filter function to be applied to context items.
        doc (DB.Document, optional):
            source document for levels; defaults to active document
        use_selection (bool, optional):
            ask if user wants to use currently selected levels.

    Returns:
        (list[DB.Level]): list of selected levels

    Examples:
        ```python
        from pyrevit import forms
        forms.select_levels()
        [<Autodesk.Revit.DB.Level object>,
         <Autodesk.Revit.DB.Level object>]
        ```
    """
    doc = doc or DOCS.doc

    # check for previously selected sheets
    if use_selection:
        current_selected_levels = revit.get_selection().include(DB.Level).elements

        if filterfunc:
            current_selected_levels = filter(filterfunc, current_selected_levels)

        if current_selected_levels and ask_to_use_selected(
            "levels", count=len(current_selected_levels), multiple=multiple
        ):
            return current_selected_levels if multiple else current_selected_levels[0]

    all_levels = revit.query.get_elements_by_categories(
        [DB.BuiltInCategory.OST_Levels], doc=doc
    )

    if filterfunc:
        all_levels = filter(filterfunc, all_levels)

    selected_levels = SelectFromList.show(
        sorted([LevelOption(x) for x in all_levels], key=lambda x: x.Elevation),
        title=title,
        button_name=button_name,
        width=width,
        multiselect=multiple,
        checked_only=True,
    )
    return selected_levels

select_viewtemplates(title='Select View Templates', button_name='Select', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=True, filterfunc=None, doc=None)

Standard form for selecting view templates.

Parameters:

Name	Type	Description	Default
title	str	list window title	'Select View Templates'
button_name	str	list window button caption	'Select'
width	int	width of list window	DEFAULT_INPUTWINDOW_WIDTH
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
filterfunc	function	filter function to be applied to context items.	None
doc	Document	source document for views; defaults to active document	None

Returns:

Type	Description
list[View]	list of selected view templates

Examples:

from pyrevit import forms
forms.select_viewtemplates()
[<Autodesk.Revit.DB.View object>,
 <Autodesk.Revit.DB.View object>]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_viewtemplates(
    title="Select View Templates",
    button_name="Select",
    width=DEFAULT_INPUTWINDOW_WIDTH,
    multiple=True,
    filterfunc=None,
    doc=None,
):
    """Standard form for selecting view templates.

    Args:
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        width (int, optional): width of list window
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        filterfunc (function):
            filter function to be applied to context items.
        doc (DB.Document, optional):
            source document for views; defaults to active document

    Returns:
        (list[DB.View]): list of selected view templates

    Examples:
        ```python
        from pyrevit import forms
        forms.select_viewtemplates()
        [<Autodesk.Revit.DB.View object>,
         <Autodesk.Revit.DB.View object>]
        ```
    """
    doc = doc or DOCS.doc
    all_viewtemplates = revit.query.get_all_view_templates(doc=doc)

    if filterfunc:
        all_viewtemplates = filter(filterfunc, all_viewtemplates)

    selected_viewtemplates = SelectFromList.show(
        sorted([ViewOption(x) for x in all_viewtemplates], key=lambda x: x.name),
        title=title,
        button_name=button_name,
        width=width,
        multiselect=multiple,
        checked_only=True,
    )

    return selected_viewtemplates

select_schedules(title='Select Schedules', button_name='Select', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=True, filterfunc=None, doc=None)

Standard form for selecting schedules.

Parameters:

Name	Type	Description	Default
title	str	list window title	'Select Schedules'
button_name	str	list window button caption	'Select'
width	int	width of list window	DEFAULT_INPUTWINDOW_WIDTH
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
filterfunc	function	filter function to be applied to context items.	None
doc	Document	source document for views; defaults to active document	None

Returns:

Type	Description
list[ViewSchedule]	list of selected schedules

Examples:

from pyrevit import forms
forms.select_schedules()
[<Autodesk.Revit.DB.ViewSchedule object>,
 <Autodesk.Revit.DB.ViewSchedule object>]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_schedules(
    title="Select Schedules",
    button_name="Select",
    width=DEFAULT_INPUTWINDOW_WIDTH,
    multiple=True,
    filterfunc=None,
    doc=None,
):
    """Standard form for selecting schedules.

    Args:
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        width (int, optional): width of list window
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        filterfunc (function):
            filter function to be applied to context items.
        doc (DB.Document, optional):
            source document for views; defaults to active document

    Returns:
        (list[DB.ViewSchedule]): list of selected schedules

    Examples:
        ```python
        from pyrevit import forms
        forms.select_schedules()
        [<Autodesk.Revit.DB.ViewSchedule object>,
         <Autodesk.Revit.DB.ViewSchedule object>]
        ```
    """
    doc = doc or DOCS.doc
    all_schedules = revit.query.get_all_schedules(doc=doc)

    if filterfunc:
        all_schedules = filter(filterfunc, all_schedules)

    selected_schedules = SelectFromList.show(
        sorted([ViewOption(x) for x in all_schedules], key=lambda x: x.name),
        title=title,
        button_name=button_name,
        width=width,
        multiselect=multiple,
        checked_only=True,
    )

    return selected_schedules

select_open_docs(title='Select Open Documents', button_name='OK', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=True, check_more_than_one=True, filterfunc=None)

Standard form for selecting open documents.

Parameters:

Name	Type	Description	Default
title	str	list window title	'Select Open Documents'
button_name	str	list window button caption	'OK'
width	int	width of list window	DEFAULT_INPUTWINDOW_WIDTH
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
check_more_than_one	bool		True
filterfunc	function	filter function to be applied to context items.	None

Returns:

Type	Description
list[Document]	list of selected documents

Examples:

from pyrevit import forms
forms.select_open_docs()
[<Autodesk.Revit.DB.Document object>,
 <Autodesk.Revit.DB.Document object>]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_open_docs(
    title="Select Open Documents",
    button_name="OK",
    width=DEFAULT_INPUTWINDOW_WIDTH,  # pylint: disable=W0613
    multiple=True,
    check_more_than_one=True,
    filterfunc=None,
):
    """Standard form for selecting open documents.

    Args:
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        width (int, optional): width of list window
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        check_more_than_one (bool, optional):
        filterfunc (function):
            filter function to be applied to context items.

    Returns:
        (list[DB.Document]): list of selected documents

    Examples:
        ```python
        from pyrevit import forms
        forms.select_open_docs()
        [<Autodesk.Revit.DB.Document object>,
         <Autodesk.Revit.DB.Document object>]
        ```
    """
    # find open documents other than the active doc
    open_docs = [d for d in revit.docs if not d.IsLinked]  # pylint: disable=E1101
    if check_more_than_one:
        open_docs.remove(revit.doc)  # pylint: disable=E1101

    if not open_docs:
        alert(
            "Only one active document is found. "
            "At least two documents must be open. "
            "Operation cancelled."
        )
        return

    return SelectFromList.show(
        open_docs,
        name_attr="Title",
        multiselect=multiple,
        title=title,
        button_name=button_name,
        filterfunc=filterfunc,
    )

select_titleblocks(title='Select Titleblock', button_name='Select', no_tb_option='No Title Block', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=False, filterfunc=None, doc=None)

Standard form for selecting a titleblock.

Parameters:

Name	Type	Description	Default
title	str	list window title	'Select Titleblock'
button_name	str	list window button caption	'Select'
no_tb_option	str	name of option for no title block	'No Title Block'
width	int	width of list window	DEFAULT_INPUTWINDOW_WIDTH
multiple	bool	allow multi-selection (uses check boxes). defaults to False	False
filterfunc	function	filter function to be applied to context items.	None
doc	Document	source document for titleblocks; defaults to active document	None

Returns:

Type	Description
ElementId	selected titleblock id.

Examples:

from pyrevit import forms
forms.select_titleblocks()
<Autodesk.Revit.DB.ElementId object>

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_titleblocks(
    title="Select Titleblock",
    button_name="Select",
    no_tb_option="No Title Block",
    width=DEFAULT_INPUTWINDOW_WIDTH,
    multiple=False,
    filterfunc=None,
    doc=None,
):
    """Standard form for selecting a titleblock.

    Args:
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        no_tb_option (str, optional): name of option for no title block
        width (int, optional): width of list window
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to False
        filterfunc (function):
            filter function to be applied to context items.
        doc (DB.Document, optional):
            source document for titleblocks; defaults to active document

    Returns:
        (DB.ElementId): selected titleblock id.

    Examples:
        ```python
        from pyrevit import forms
        forms.select_titleblocks()
        <Autodesk.Revit.DB.ElementId object>
        ```
    """
    doc = doc or DOCS.doc
    titleblocks = (
        DB.FilteredElementCollector(doc)
        .OfCategory(DB.BuiltInCategory.OST_TitleBlocks)
        .WhereElementIsElementType()
        .ToElements()
    )

    tblock_dict = {
        "{}: {}".format(tb.FamilyName, revit.query.get_name(tb)): tb.Id
        for tb in titleblocks
    }
    tblock_dict[no_tb_option] = DB.ElementId.InvalidElementId
    selected_titleblocks = SelectFromList.show(
        sorted(tblock_dict.keys()),
        title=title,
        button_name=button_name,
        width=width,
        multiselect=multiple,
        filterfunc=filterfunc,
    )
    if selected_titleblocks:
        if multiple:
            return [tblock_dict[x] for x in selected_titleblocks]
        else:
            return tblock_dict[selected_titleblocks]

select_swatch(title='Select Color Swatch', button_name='Select')

Standard form for selecting a color swatch.

Parameters:

Name	Type	Description	Default
title	str	swatch list window title	'Select Color Swatch'
button_name	str	swatch list window button caption	'Select'

Returns:

Type	Description
RGB	rgb color

Examples:

from pyrevit import forms
forms.select_swatch(title="Select Text Color")
<RGB #CD8800>

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_swatch(title="Select Color Swatch", button_name="Select"):
    """Standard form for selecting a color swatch.

    Args:
        title (str, optional): swatch list window title
        button_name (str, optional): swatch list window button caption

    Returns:
        (pyrevit.coreutils.colors.RGB): rgb color

    Examples:
        ```python
        from pyrevit import forms
        forms.select_swatch(title="Select Text Color")
        <RGB #CD8800>
        ```
    """
    itemplate = utils.load_ctrl_template(
        os.path.join(XAML_FILES_DIR, "SwatchContainerStyle.xaml")
    )
    swatch = SelectFromList.show(
        colors.COLORS.values(),
        title=title,
        button_name=button_name,
        width=300,
        multiselect=False,
        item_template=itemplate,
    )

    return swatch

select_image(images, title='Select Image', button_name='Select')

Standard form for selecting an image.

Parameters:

Name	Type	Description	Default
images	list[str] | list[BitmapImage]	list of image file paths or bitmaps	required
title	str	swatch list window title	'Select Image'
button_name	str	swatch list window button caption	'Select'

Returns:

Type	Description
str	path of the selected image

Examples:

from pyrevit import forms
forms.select_image(['C:/path/to/image1.png',
                    'C:/path/to/image2.png'],
                    title="Select Variation")
'C:/path/to/image1.png'

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_image(images, title="Select Image", button_name="Select"):
    """Standard form for selecting an image.

    Args:
        images (list[str] | list[framework.Imaging.BitmapImage]):
            list of image file paths or bitmaps
        title (str, optional): swatch list window title
        button_name (str, optional): swatch list window button caption

    Returns:
        (str): path of the selected image

    Examples:
        ```python
        from pyrevit import forms
        forms.select_image(['C:/path/to/image1.png',
                            'C:/path/to/image2.png'],
                            title="Select Variation")
        'C:/path/to/image1.png'
        ```
    """
    ptemplate = utils.load_itemspanel_template(
        os.path.join(XAML_FILES_DIR, "ImageListPanelStyle.xaml")
    )

    itemplate = utils.load_ctrl_template(
        os.path.join(XAML_FILES_DIR, "ImageListContainerStyle.xaml")
    )

    bitmap_images = {}
    for imageobj in images:
        if isinstance(imageobj, str):
            img = utils.bitmap_from_file(imageobj)
            if img:
                bitmap_images[img] = imageobj
        elif isinstance(imageobj, framework.Imaging.BitmapImage):
            bitmap_images[imageobj] = imageobj

    selected_image = SelectFromList.show(
        sorted(bitmap_images.keys(), key=lambda x: x.UriSource.AbsolutePath),
        title=title,
        button_name=button_name,
        width=500,
        multiselect=False,
        item_template=itemplate,
        items_panel_template=ptemplate,
    )

    return bitmap_images.get(selected_image, None)

select_parameters(src_element, title='Select Parameters', button_name='Select', multiple=True, filterfunc=None, include_instance=True, include_type=True, exclude_readonly=True)

Standard form for selecting parameters from given element.

Parameters:

Name	Type	Description	Default
src_element	Element	source element	required
title	str	list window title	'Select Parameters'
button_name	str	list window button caption	'Select'
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
filterfunc	function	filter function to be applied to context items.	None
include_instance	bool	list instance parameters	True
include_type	bool	list type parameters	True
exclude_readonly	bool	only shows parameters that are editable	True

Returns:

Type	Description
list[ParamDef]	list of paramdef objects

Examples:

forms.select_parameter(
    src_element,
    title='Select Parameters',
    multiple=True,
    include_instance=True,
    include_type=True
)
[<ParamDef >, <ParamDef >]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_parameters(
    src_element,
    title="Select Parameters",
    button_name="Select",
    multiple=True,
    filterfunc=None,
    include_instance=True,
    include_type=True,
    exclude_readonly=True,
):
    """Standard form for selecting parameters from given element.

    Args:
        src_element (DB.Element): source element
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        filterfunc (function):
            filter function to be applied to context items.
        include_instance (bool, optional): list instance parameters
        include_type (bool, optional): list type parameters
        exclude_readonly (bool, optional): only shows parameters that are editable

    Returns:
        (list[ParamDef]): list of paramdef objects

    Examples:
        ```python
        forms.select_parameter(
            src_element,
            title='Select Parameters',
            multiple=True,
            include_instance=True,
            include_type=True
        )
        [<ParamDef >, <ParamDef >]
        ```
    """
    param_defs = []
    non_storage_type = coreutils.get_enum_none(DB.StorageType)
    if include_instance:
        # collect instance parameters
        param_defs.extend(
            [
                _make_param_def(x, istype=False)
                for x in src_element.Parameters
                if x.StorageType != non_storage_type
            ]
        )

    if include_type:
        # collect type parameters
        src_type = revit.query.get_type(src_element) if src_element else None
        if src_type is not None:
            param_defs.extend(
                [
                    _make_param_def(x, istype=True)
                    for x in src_type.Parameters
                    if x.StorageType != non_storage_type
                ]
            )

    if exclude_readonly:
        param_defs = filter(lambda x: not x.isreadonly, param_defs)

    if filterfunc:
        param_defs = filter(filterfunc, param_defs)

    param_defs.sort(key=lambda x: x.name)

    itemplate = utils.load_ctrl_template(
        os.path.join(XAML_FILES_DIR, "ParameterItemStyle.xaml")
    )
    selected_params = SelectFromList.show(
        param_defs,
        title=title,
        button_name=button_name,
        width=500,
        multiselect=multiple,
        item_template=itemplate,
    )

    return selected_params

select_family_parameters(family_doc, title='Select Parameters', button_name='Select', multiple=True, filterfunc=None, include_instance=True, include_type=True, include_builtin=True, include_labeled=True, include_associated=True)

Standard form for selecting parameters from given family document.

Parameters:

Name	Type	Description	Default
family_doc	Document	source family document	required
title	str	list window title	'Select Parameters'
button_name	str	list window button caption	'Select'
multiple	bool	allow multi-selection (uses check boxes). defaults to True	True
filterfunc	function	filter function to be applied to context items.	None
include_instance	bool	list instance parameters	True
include_type	bool	list type parameters	True
include_builtin	bool	list builtin parameters	True
include_labeled	bool	list parameters used as labels	True
include_associated	bool	list parameters associated to others	True

Returns:

Type	Description
list[FamilyParameter]	list of family parameter objects

Examples:

forms.select_family_parameters(
    family_doc,
    title='Select Parameters',
    multiple=True,
    include_instance=True,
    include_type=True
)
[<DB.FamilyParameter >, <DB.FamilyParameter >]

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def select_family_parameters(
    family_doc,
    title="Select Parameters",
    button_name="Select",
    multiple=True,
    filterfunc=None,
    include_instance=True,
    include_type=True,
    include_builtin=True,
    include_labeled=True,
    include_associated=True,
):
    """Standard form for selecting parameters from given family document.

    Args:
        family_doc (DB.Document): source family document
        title (str, optional): list window title
        button_name (str, optional): list window button caption
        multiple (bool, optional):
            allow multi-selection (uses check boxes). defaults to True
        filterfunc (function):
            filter function to be applied to context items.
        include_instance (bool, optional): list instance parameters
        include_type (bool, optional): list type parameters
        include_builtin (bool, optional): list builtin parameters
        include_labeled (bool, optional): list parameters used as labels
        include_associated (bool, optional):
            list parameters associated to others

    Returns:
        (list[DB.FamilyParameter]): list of family parameter objects

    Examples:
        ```python
        forms.select_family_parameters(
            family_doc,
            title='Select Parameters',
            multiple=True,
            include_instance=True,
            include_type=True
        )
        [<DB.FamilyParameter >, <DB.FamilyParameter >]
        ```
    """
    family_doc = family_doc or DOCS.doc
    family_params = revit.query.get_family_parameters(family_doc)
    # get all params used in labeles
    label_param_ids = [
        x.Id for x in revit.query.get_family_label_parameters(family_doc)
    ]

    if filterfunc:
        family_params = filter(filterfunc, family_params)

    param_defs = []
    get_elementid_value = get_elementid_value_func()
    for family_param in family_params:
        if not include_instance and family_param.IsInstance:
            continue
        if not include_type and not family_param.IsInstance:
            continue
        if not include_builtin and get_elementid_value(family_param.Id) < 0:
            continue
        if not include_labeled and family_param.Id in label_param_ids:
            continue

        associated_to_others = not family_param.AssociatedParameters.IsEmpty
        if not include_associated and associated_to_others:
            continue

        param_defs.append(
            FamilyParamOption(
                family_param,
                builtin=get_elementid_value(family_param.Id) < 0,
                labeled=family_param.Id in label_param_ids,
                associated=associated_to_others,
            )
        )

    param_defs.sort(key=lambda x: x.name)

    itemplate = utils.load_ctrl_template(
        os.path.join(XAML_FILES_DIR, "FamilyParameterItemStyle.xaml")
    )
    selected_params = SelectFromList.show(
        {
            "All Parameters": param_defs,
            "Type Parameters": [x for x in param_defs if x.istype],
            "Built-in Parameters": [x for x in param_defs if x.isbuiltin],
            "Used as Label": [x for x in param_defs if x.islabeled],
            "Associated to Others": [x for x in param_defs if x.isassociated],
        },
        title=title,
        button_name=button_name,
        group_selector_title="Parameter Filters:",
        width=450,
        multiselect=multiple,
        item_template=itemplate,
    )

    return selected_params

alert(msg, title=None, sub_msg=None, expanded=None, footer='', ok=True, cancel=False, yes=False, no=False, retry=False, warn_icon=True, options=None, exitscript=False)

Show a task dialog with given message.

Parameters:

Name	Type	Description	Default
msg	str	message to be displayed	required
title	str	task dialog title	None
sub_msg	str	sub message, use html to create clickable links	None
expanded	str	expanded area message	None
footer	str	footer text	''
ok	bool	show OK button, defaults to True	True
cancel	bool	show Cancel button, defaults to False	False
yes	bool	show Yes button, defaults to False	False
no	bool	show NO button, defaults to False	False
retry	bool	show Retry button, defaults to False	False
warn_icon	bool	show warning icon	True
options	list[str]	list of command link titles in order	None
exitscript	bool	exit if cancel or no, defaults to False	False

Returns:

Type	Description
bool	True if okay, yes, or retry, otherwise False

Examples:

from pyrevit import forms
forms.alert('Are you sure?',
            sub_msg='<a href=\"https://discourse.pyrevitlabs.io/ \">Click here if you are not sure and want to go to the pyRevit Forum</a>',
            ok=False, yes=True, no=True, exitscript=True)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def alert(
    msg,
    title=None,
    sub_msg=None,
    expanded=None,
    footer="",
    ok=True,
    cancel=False,
    yes=False,
    no=False,
    retry=False,
    warn_icon=True,
    options=None,
    exitscript=False,
):
    r"""Show a task dialog with given message.

    Args:
        msg (str): message to be displayed
        title (str, optional): task dialog title
        sub_msg (str, optional): sub message, use html to create clickable links
        expanded (str, optional): expanded area message
        footer (str, optional): footer text
        ok (bool, optional): show OK button, defaults to True
        cancel (bool, optional): show Cancel button, defaults to False
        yes (bool, optional): show Yes button, defaults to False
        no (bool, optional): show NO button, defaults to False
        retry (bool, optional): show Retry button, defaults to False
        warn_icon (bool, optional): show warning icon
        options (list[str], optional): list of command link titles in order
        exitscript (bool, optional): exit if cancel or no, defaults to False

    Returns:
        (bool): True if okay, yes, or retry, otherwise False

    Examples:
        ```python
        from pyrevit import forms
        forms.alert('Are you sure?',
                    sub_msg='<a href=\"https://discourse.pyrevitlabs.io/ \">Click here if you are not sure and want to go to the pyRevit Forum</a>',
                    ok=False, yes=True, no=True, exitscript=True)
        ```
    """
    # BUILD DIALOG
    cmd_name = EXEC_PARAMS.command_name
    if not title:
        title = cmd_name if cmd_name else "pyRevit"
    tdlg = UI.TaskDialog(title)

    # process input types
    just_ok = ok and not any([cancel, yes, no, retry])

    options = options or []
    # add command links if any
    if options:
        clinks = coreutils.get_enum_values(UI.TaskDialogCommandLinkId)
        max_clinks = len(clinks)
        for idx, cmd in enumerate(options):
            if idx < max_clinks:
                tdlg.AddCommandLink(clinks[idx], cmd)
    # otherwise add buttons
    else:
        buttons = coreutils.get_enum_none(UI.TaskDialogCommonButtons)
        if yes:
            buttons |= UI.TaskDialogCommonButtons.Yes
        elif ok:
            buttons |= UI.TaskDialogCommonButtons.Ok

        if cancel:
            buttons |= UI.TaskDialogCommonButtons.Cancel
        if no:
            buttons |= UI.TaskDialogCommonButtons.No
        if retry:
            buttons |= UI.TaskDialogCommonButtons.Retry
        tdlg.CommonButtons = buttons

    # set texts
    tdlg.MainInstruction = msg
    tdlg.MainContent = sub_msg
    tdlg.ExpandedContent = expanded
    if footer:
        footer = footer.strip() + "\n"
    tdlg.FooterText = footer + "pyRevit {}".format(
        versionmgr.get_pyrevit_version().get_formatted()
    )
    tdlg.TitleAutoPrefix = False

    # set icon
    tdlg.MainIcon = (
        UI.TaskDialogIcon.TaskDialogIconWarning
        if warn_icon
        else UI.TaskDialogIcon.TaskDialogIconNone
    )

    # tdlg.VerificationText = 'verif'

    # SHOW DIALOG
    res = tdlg.Show()

    # PROCESS REPONSES
    # positive response
    mlogger.debug("alert result: %s", res)
    if (
        res == UI.TaskDialogResult.Ok
        or res == UI.TaskDialogResult.Yes
        or res == UI.TaskDialogResult.Retry
    ):
        if just_ok and exitscript:
            sys.exit()
        return True
    # negative response
    elif (
        res == coreutils.get_enum_none(UI.TaskDialogResult)
        or res == UI.TaskDialogResult.Cancel
        or res == UI.TaskDialogResult.No
    ):
        if exitscript:
            sys.exit()
        else:
            return False

    # command link response
    elif "CommandLink" in str(res):
        tdresults = sorted(
            [
                x
                for x in coreutils.get_enum_values(UI.TaskDialogResult)
                if "CommandLink" in str(x)
            ]
        )
        residx = tdresults.index(res)
        return options[residx]
    elif exitscript:
        sys.exit()
    else:
        return False

alert_ifnot(condition, msg, *args, **kwargs)

Show a task dialog with given message if condition is NOT met.

Parameters:

Name	Type	Description	Default
condition	bool	condition to test	required
msg	str	message to be displayed	required
*args	Any	additional arguments	()
**kwargs	Any	additional keyword arguments	{}

Other Parameters:

Name	Type	Description
title	str	task dialog title
ok	bool	show OK button, defaults to True
cancel	bool	show Cancel button, defaults to False
yes	bool	show Yes button, defaults to False
no	bool	show NO button, defaults to False
retry	bool	show Retry button, defaults to False
exitscript	bool	exit if cancel or no, defaults to False

Returns:

Type	Description
bool	True if okay, yes, or retry, otherwise False

Examples:

from pyrevit import forms
forms.alert_ifnot(value > 12,
                  'Are you sure?',
                   ok=False, yes=True, no=True, exitscript=True)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def alert_ifnot(condition, msg, *args, **kwargs):
    """Show a task dialog with given message if condition is NOT met.

    Args:
        condition (bool): condition to test
        msg (str): message to be displayed
        *args (Any): additional arguments
        **kwargs (Any): additional keyword arguments

    Keyword Args:
        title (str, optional): task dialog title
        ok (bool, optional): show OK button, defaults to True
        cancel (bool, optional): show Cancel button, defaults to False
        yes (bool, optional): show Yes button, defaults to False
        no (bool, optional): show NO button, defaults to False
        retry (bool, optional): show Retry button, defaults to False
        exitscript (bool, optional): exit if cancel or no, defaults to False

    Returns:
        (bool): True if okay, yes, or retry, otherwise False

    Examples:
        ```python
        from pyrevit import forms
        forms.alert_ifnot(value > 12,
                          'Are you sure?',
                           ok=False, yes=True, no=True, exitscript=True)
        ```
    """
    if not condition:
        return alert(msg, *args, **kwargs)

pick_folder(title=None, owner=None)

Show standard windows pick folder dialog.

Parameters:

Name	Type	Description	Default
title	str	title for the window	None
owner	object	owner of the dialog	None

Returns:

Type	Description
str	folder path

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def pick_folder(title=None, owner=None):
    """Show standard windows pick folder dialog.

    Args:
        title (str, optional): title for the window
        owner (object, optional): owner of the dialog

    Returns:
        (str): folder path
    """
    if CPDialogs:
        fb_dlg = CPDialogs.CommonOpenFileDialog()
        fb_dlg.IsFolderPicker = True
        if title:
            fb_dlg.Title = title

        res = CPDialogs.CommonFileDialogResult.Cancel
        if owner:
            res = fb_dlg.ShowDialog(owner)
        else:
            res = fb_dlg.ShowDialog()

        if res == CPDialogs.CommonFileDialogResult.Ok:
            return fb_dlg.FileName
    else:
        fb_dlg = Forms.FolderBrowserDialog()
        if title:
            fb_dlg.Description = title
        if fb_dlg.ShowDialog() == Forms.DialogResult.OK:
            return fb_dlg.SelectedPath

result_item_result_clicked(sender, e, debug=False)

Callback for a result item click event.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def result_item_result_clicked(sender, e, debug=False):
    """Callback for a result item click event."""
    if debug:
        print("Result clicked")  # using print_md here will break the script
    pass

show_balloon(header, text, tooltip='', group='', is_favourite=False, is_new=False, timestamp=None, click_result=result_item_result_clicked)

Show ballon in the info center section.

Parameters:

Name	Type	Description	Default
header	str	Category section (Bold)	required
text	str	Title section (Regular)	required
tooltip	str	Tooltip	''
group	str	Group	''
is_favourite	bool	Add a blue star before header	False
is_new	bool	Flag to new	False
timestamp	str	Set timestamp	None
click_result	def	Executed after a click event	result_item_result_clicked

Examples:

from pyrevit import forms
date = '2019-01-01 00:00:00'
date = datetime.datetime.strptime(date, '%Y-%m-%d %H:%M:%S')
forms.show_balloon("my header", "Lorem ipsum", tooltip='tooltip',   group='group', is_favourite=True, is_new=True, timestamp = date, click_result = forms.result_item_result_clicked)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def show_balloon(
    header,
    text,
    tooltip="",
    group="",
    is_favourite=False,
    is_new=False,
    timestamp=None,
    click_result=result_item_result_clicked,
):
    r"""Show ballon in the info center section.

    Args:
        header (str): Category section (Bold)
        text (str): Title section (Regular)
        tooltip (str): Tooltip
        group (str): Group
        is_favourite (bool): Add a blue star before header
        is_new (bool): Flag to new
        timestamp (str): Set timestamp
        click_result (def): Executed after a click event

    Examples:
        ```python
        from pyrevit import forms
        date = '2019-01-01 00:00:00'
        date = datetime.datetime.strptime(date, '%Y-%m-%d %H:%M:%S')
        forms.show_balloon("my header", "Lorem ipsum", tooltip='tooltip',   group='group', is_favourite=True, is_new=True, timestamp = date, click_result = forms.result_item_result_clicked)
        ```
    """
    result_item = Autodesk.Internal.InfoCenter.ResultItem()
    result_item.Category = header
    result_item.Title = text
    result_item.TooltipText = tooltip
    result_item.Group = group
    result_item.IsFavorite = is_favourite
    result_item.IsNew = is_new
    if timestamp:
        result_item.Timestamp = timestamp
    result_item.ResultClicked += click_result
    balloon = Autodesk.Windows.ComponentManager.InfoCenterPaletteManager.ShowBalloon(
        result_item
    )
    return balloon

pick_file(file_ext='*', files_filter='', init_dir='', restore_dir=True, multi_file=False, unc_paths=False, title=None)

Pick file dialog to select a destination file.

Parameters:

Name	Type	Description	Default
file_ext	str	file extension	'*'
files_filter	str	file filter	''
init_dir	str	initial directory	''
restore_dir	bool	restore last directory	True
multi_file	bool	allow select multiple files	False
unc_paths	bool	return unc paths	False
title	str	text to show in the title bar	None

Returns:

Type	Description
str | list[str]	file path or list of file paths if multi_file=True

Examples:

from pyrevit import forms
forms.pick_file(file_ext='csv')
r'C:\output\somefile.csv'

forms.pick_file(file_ext='csv', multi_file=True)
[r'C:\output\somefile1.csv', r'C:\output\somefile2.csv']

forms.pick_file(files_filter='All Files (*.*)|*.*|'
                                 'Excel Workbook (*.xlsx)|*.xlsx|'
                                 'Excel 97-2003 Workbook|*.xls',
                    multi_file=True)
[r'C:\output\somefile1.xlsx', r'C:\output\somefile2.xls']

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def pick_file(
    file_ext="*",
    files_filter="",
    init_dir="",
    restore_dir=True,
    multi_file=False,
    unc_paths=False,
    title=None,
):
    r"""Pick file dialog to select a destination file.

    Args:
        file_ext (str): file extension
        files_filter (str): file filter
        init_dir (str): initial directory
        restore_dir (bool): restore last directory
        multi_file (bool): allow select multiple files
        unc_paths (bool): return unc paths
        title (str): text to show in the title bar

    Returns:
        (str | list[str]): file path or list of file paths if multi_file=True

    Examples:
        ```python
        from pyrevit import forms
        forms.pick_file(file_ext='csv')
        r'C:\output\somefile.csv'
        ```

        ```python
        forms.pick_file(file_ext='csv', multi_file=True)
        [r'C:\output\somefile1.csv', r'C:\output\somefile2.csv']
        ```

        ```python
        forms.pick_file(files_filter='All Files (*.*)|*.*|'
                                         'Excel Workbook (*.xlsx)|*.xlsx|'
                                         'Excel 97-2003 Workbook|*.xls',
                            multi_file=True)
        [r'C:\output\somefile1.xlsx', r'C:\output\somefile2.xls']
        ```
    """
    of_dlg = Forms.OpenFileDialog()
    if files_filter:
        of_dlg.Filter = files_filter
    else:
        of_dlg.Filter = "|*.{}".format(file_ext)
    of_dlg.RestoreDirectory = restore_dir
    of_dlg.Multiselect = multi_file
    if init_dir:
        of_dlg.InitialDirectory = init_dir
    if title:
        of_dlg.Title = title
    if of_dlg.ShowDialog() == Forms.DialogResult.OK:
        if multi_file:
            if unc_paths:
                return [coreutils.dletter_to_unc(x) for x in of_dlg.FileNames]
            return of_dlg.FileNames
        else:
            if unc_paths:
                return coreutils.dletter_to_unc(of_dlg.FileName)
            return of_dlg.FileName

save_file(file_ext='', files_filter='', init_dir='', default_name='', restore_dir=True, unc_paths=False, title=None)

Save file dialog to select a destination file for data.

Parameters:

Name	Type	Description	Default
file_ext	str	file extension	''
files_filter	str	file filter	''
init_dir	str	initial directory	''
default_name	str	default file name	''
restore_dir	bool	restore last directory	True
unc_paths	bool	return unc paths	False
title	str	text to show in the title bar	None

Returns:

Type	Description
str	file path

Examples:

from pyrevit import forms
forms.save_file(file_ext='csv')
r'C:\output\somefile.csv'

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def save_file(
    file_ext="",
    files_filter="",
    init_dir="",
    default_name="",
    restore_dir=True,
    unc_paths=False,
    title=None,
):
    r"""Save file dialog to select a destination file for data.

    Args:
        file_ext (str): file extension
        files_filter (str): file filter
        init_dir (str): initial directory
        default_name (str): default file name
        restore_dir (bool): restore last directory
        unc_paths (bool): return unc paths
        title (str): text to show in the title bar

    Returns:
        (str): file path

    Examples:
        ```python
        from pyrevit import forms
        forms.save_file(file_ext='csv')
        r'C:\output\somefile.csv'
        ```
    """
    sf_dlg = Forms.SaveFileDialog()
    if files_filter:
        sf_dlg.Filter = files_filter
    else:
        sf_dlg.Filter = "|*.{}".format(file_ext)
    sf_dlg.RestoreDirectory = restore_dir
    if init_dir:
        sf_dlg.InitialDirectory = init_dir
    if title:
        sf_dlg.Title = title

    # setting default filename
    sf_dlg.FileName = default_name

    if sf_dlg.ShowDialog() == Forms.DialogResult.OK:
        if unc_paths:
            return coreutils.dletter_to_unc(sf_dlg.FileName)
        return sf_dlg.FileName

pick_excel_file(save=False, title=None)

File pick/save dialog for an excel file.

Parameters:

Name	Type	Description	Default
save	bool	show file save dialog, instead of file pick dialog	False
title	str	text to show in the title bar	None

Returns:

Type	Description
str	file path

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def pick_excel_file(save=False, title=None):
    """File pick/save dialog for an excel file.

    Args:
        save (bool): show file save dialog, instead of file pick dialog
        title (str): text to show in the title bar

    Returns:
        (str): file path
    """
    if save:
        return save_file(file_ext="xlsx")
    return pick_file(
        files_filter="Excel Workbook (*.xlsx)|*.xlsx|" "Excel 97-2003 Workbook|*.xls",
        title=title,
    )

save_excel_file(title=None)

File save dialog for an excel file.

Parameters:

Name	Type	Description	Default
title	str	text to show in the title bar	None

Returns:

Type	Description
str	file path

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def save_excel_file(title=None):
    """File save dialog for an excel file.

    Args:
        title (str): text to show in the title bar

    Returns:
        (str): file path
    """
    return pick_excel_file(save=True, title=title)

check_workshared(doc=None, message='Model is not workshared.')

Verify if model is workshared and notify user if not.

Parameters:

Name	Type	Description	Default
doc	Document	target document, current of not provided	None
message	str	prompt message if returning False	'Model is not workshared.'

Returns:

Type	Description
bool	True if doc is workshared

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_workshared(doc=None, message="Model is not workshared."):
    """Verify if model is workshared and notify user if not.

    Args:
        doc (DB.Document): target document, current of not provided
        message (str): prompt message if returning False

    Returns:
        (bool): True if doc is workshared
    """
    doc = doc or DOCS.doc
    if not doc.IsWorkshared:
        alert(message, warn_icon=True)
        return False
    return True

check_selection(exitscript=False, message='At least one element must be selected.')

Verify if selection is not empty notify user if it is.

Parameters:

Name	Type	Description	Default
exitscript	bool	exit script if returning False	False
message	str	prompt message if returning False	'At least one element must be selected.'

Returns:

Type	Description
bool	True if selection has at least one item

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_selection(exitscript=False, message="At least one element must be selected."):
    """Verify if selection is not empty notify user if it is.

    Args:
        exitscript (bool): exit script if returning False
        message (str): prompt message if returning False

    Returns:
        (bool): True if selection has at least one item
    """
    if revit.get_selection().is_empty:
        alert(message, exitscript=exitscript)
        return False
    return True

check_familydoc(doc=None, family_cat=None, exitscript=False)

Verify document is a Family and notify user if not.

Parameters:

Name	Type	Description	Default
doc	Document	target document, current of not provided	None
family_cat	str	family category name	None
exitscript	bool	exit script if returning False	False

Returns:

Type	Description
bool	True if doc is a Family and of provided category

Examples:

from pyrevit import forms
forms.check_familydoc(doc=revit.doc, family_cat='Data Devices')
True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_familydoc(doc=None, family_cat=None, exitscript=False):
    """Verify document is a Family and notify user if not.

    Args:
        doc (DB.Document): target document, current of not provided
        family_cat (str): family category name
        exitscript (bool): exit script if returning False

    Returns:
        (bool): True if doc is a Family and of provided category

    Examples:
        ```python
        from pyrevit import forms
        forms.check_familydoc(doc=revit.doc, family_cat='Data Devices')
        True
        ```
    """
    doc = doc or DOCS.doc
    family_cat = revit.query.get_category(family_cat)
    if doc.IsFamilyDocument and family_cat:
        if doc.OwnerFamily.FamilyCategory.Id == family_cat.Id:
            return True
    elif doc.IsFamilyDocument and not family_cat:
        return True

    family_type_msg = " of type {}".format(family_cat.Name) if family_cat else ""
    alert(
        "Active document must be a Family document{}.".format(family_type_msg),
        exitscript=exitscript,
    )
    return False

check_modeldoc(doc=None, exitscript=False)

Verify document is a not a Model and notify user if not.

Parameters:

Name	Type	Description	Default
doc	Document	target document, current of not provided	None
exitscript	bool	exit script if returning False	False

Returns:

Type	Description
bool	True if doc is a Model

Examples:

from pyrevit import forms
forms.check_modeldoc(doc=revit.doc)
True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_modeldoc(doc=None, exitscript=False):
    """Verify document is a not a Model and notify user if not.

    Args:
        doc (DB.Document): target document, current of not provided
        exitscript (bool): exit script if returning False

    Returns:
        (bool): True if doc is a Model

    Examples:
        ```python
        from pyrevit import forms
        forms.check_modeldoc(doc=revit.doc)
        True
        ```
    """
    doc = doc or DOCS.doc
    if not doc.IsFamilyDocument:
        return True

    alert(
        "Active document must be a Revit model (not a Family).", exitscript=exitscript
    )
    return False

check_modelview(view, exitscript=False)

Verify target view is a model view.

Parameters:

Name	Type	Description	Default
view	View	target view	required
exitscript	bool	exit script if returning False	False

Returns:

Type	Description
bool	True if view is model view

Examples:

from pyrevit import forms
forms.check_modelview(view=revit.active_view)
True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_modelview(view, exitscript=False):
    """Verify target view is a model view.

    Args:
        view (DB.View): target view
        exitscript (bool): exit script if returning False

    Returns:
        (bool): True if view is model view

    Examples:
        ```python
        from pyrevit import forms
        forms.check_modelview(view=revit.active_view)
        True
        ```
    """
    if not isinstance(view, (DB.View3D, DB.ViewPlan, DB.ViewSection)):
        alert("Active view must be a model view.", exitscript=exitscript)
        return False
    return True

check_viewtype(view, view_type, exitscript=False)

Verify target view is of given type.

Parameters:

Name	Type	Description	Default
view	View	target view	required
view_type	ViewType	type of view	required
exitscript	bool	exit script if returning False	False

Returns:

Type	Description
bool	True if view is of given type

Examples:

from pyrevit import forms
forms.check_viewtype(revit.active_view, DB.ViewType.DrawingSheet)
True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_viewtype(view, view_type, exitscript=False):
    """Verify target view is of given type.

    Args:
        view (DB.View): target view
        view_type (DB.ViewType): type of view
        exitscript (bool): exit script if returning False

    Returns:
        (bool): True if view is of given type

    Examples:
        ```python
        from pyrevit import forms
        forms.check_viewtype(revit.active_view, DB.ViewType.DrawingSheet)
        True
        ```
    """
    if view.ViewType != view_type:
        alert(
            "Active view must be a {}.".format(
                " ".join(coreutils.split_words(str(view_type)))
            ),
            exitscript=exitscript,
        )
        return False
    return True

check_graphicalview(view, exitscript=False)

Verify target view is a graphical view.

Parameters:

Name	Type	Description	Default
view	View	target view	required
exitscript	bool	exit script if returning False	False

Returns:

Type	Description
bool	True if view is a graphical view

Examples:

from pyrevit import forms
forms.check_graphicalview(revit.active_view)
True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def check_graphicalview(view, exitscript=False):
    """Verify target view is a graphical view.

    Args:
        view (DB.View): target view
        exitscript (bool): exit script if returning False

    Returns:
        (bool): True if view is a graphical view

    Examples:
        ```python
        from pyrevit import forms
        forms.check_graphicalview(revit.active_view)
        True
        ```
    """
    if not view.Category:
        alert("Active view must be a grahical view.", exitscript=exitscript)
        return False
    return True

toast(message, title='pyRevit', appid='pyRevit', icon=None, click=None, actions=None)

Show a Windows 10 notification.

Parameters:

Name	Type	Description	Default
message	str	notification message	required
title	str	notification title	'pyRevit'
appid	str	app name (will show under message)	'pyRevit'
icon	str	file path to icon .ico file (defaults to pyRevit icon)	None
click	str	click action commands string	None
actions	dict	dictionary of button names and action strings	None

Examples:

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

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def toast(
    message, title="pyRevit", appid="pyRevit", icon=None, click=None, actions=None
):
    """Show a Windows 10 notification.

    Args:
        message (str): notification message
        title (str): notification title
        appid (str): app name (will show under message)
        icon (str): file path to icon .ico file (defaults to pyRevit icon)
        click (str): click action commands string
        actions (dict): dictionary of button names and action strings

    Examples:
        ```python
        script.toast("Hello World!",
                     title="My Script",
                     appid="MyAPP",
                     click="https://pyrevitlabs.github.io/pyRevit/",
                     actions={
                         "Open Google":"https://google.com",
                         "Open Toast64":"https://github.com/go-toast/toast"
                         })
        ```
    """
    toaster.send_toast(
        message, title=title, appid=appid, icon=icon, click=click, actions=actions
    )

ask_for_string(default=None, prompt=None, title=None, **kwargs)

Ask user to select a string value.

This is a shortcut function that configures :obj:GetValueWindow for string data types. kwargs can be used to pass on other arguments.

Parameters:

Name	Type	Description	Default
default	str	default unique string. must not be in reserved_values	None
prompt	str	prompt message	None
title	str	title message	None
kwargs	type	other arguments to be passed to :obj:GetValueWindow	{}

Returns:

Type	Description
str	selected string value

Examples:

forms.ask_for_string(
    default='some-tag',
    prompt='Enter new tag name:',
    title='Tag Manager')
'new-tag'

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def ask_for_string(default=None, prompt=None, title=None, **kwargs):
    """Ask user to select a string value.

    This is a shortcut function that configures :obj:`GetValueWindow` for
    string data types. kwargs can be used to pass on other arguments.

    Args:
        default (str): default unique string. must not be in reserved_values
        prompt (str): prompt message
        title (str): title message
        kwargs (type): other arguments to be passed to :obj:`GetValueWindow`

    Returns:
        (str): selected string value

    Examples:
        ```python
        forms.ask_for_string(
            default='some-tag',
            prompt='Enter new tag name:',
            title='Tag Manager')
        'new-tag'
        ```
    """
    return GetValueWindow.show(
        None, value_type="string", default=default, prompt=prompt, title=title, **kwargs
    )

ask_for_unique_string(reserved_values, default=None, prompt=None, title=None, **kwargs)

Ask user to select a unique string value.

This is a shortcut function that configures :obj:GetValueWindow for unique string data types. kwargs can be used to pass on other arguments.

Parameters:

Name	Type	Description	Default
reserved_values	list[str]	list of reserved (forbidden) values	required
default	str	default unique string. must not be in reserved_values	None
prompt	str	prompt message	None
title	str	title message	None
kwargs	type	other arguments to be passed to :obj:GetValueWindow	{}

Returns:

Type	Description
str	selected unique string

Examples:

forms.ask_for_unique_string(
    prompt='Enter a Unique Name',
    title=self.Title,
    reserved_values=['Ehsan', 'Gui', 'Guido'],
    owner=self)
'unique string'

In example above, owner argument is provided to be passed to underlying :obj:GetValueWindow.

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def ask_for_unique_string(
    reserved_values, default=None, prompt=None, title=None, **kwargs
):
    """Ask user to select a unique string value.

    This is a shortcut function that configures :obj:`GetValueWindow` for
    unique string data types. kwargs can be used to pass on other arguments.

    Args:
        reserved_values (list[str]): list of reserved (forbidden) values
        default (str): default unique string. must not be in reserved_values
        prompt (str): prompt message
        title (str): title message
        kwargs (type): other arguments to be passed to :obj:`GetValueWindow`

    Returns:
        (str): selected unique string

    Examples:
        ```python
        forms.ask_for_unique_string(
            prompt='Enter a Unique Name',
            title=self.Title,
            reserved_values=['Ehsan', 'Gui', 'Guido'],
            owner=self)
        'unique string'
        ```

        In example above, owner argument is provided to be passed to underlying
        :obj:`GetValueWindow`.

    """
    return GetValueWindow.show(
        None,
        value_type="string",
        default=default,
        prompt=prompt,
        title=title,
        reserved_values=reserved_values,
        **kwargs
    )

ask_for_one_item(items, default=None, prompt=None, title=None, **kwargs)

Ask user to select an item from a list of items.

This is a shortcut function that configures :obj:GetValueWindow for 'single-select' data types. kwargs can be used to pass on other arguments.

Parameters:

Name	Type	Description	Default
items	list[str]	list of items to choose from	required
default	str	default selected item	None
prompt	str	prompt message	None
title	str	title message	None
kwargs	type	other arguments to be passed to :obj:GetValueWindow	{}

Returns:

Type	Description
str	selected item

Examples:

forms.ask_for_one_item(
    ['test item 1', 'test item 2', 'test item 3'],
    default='test item 2',
    prompt='test prompt',
    title='test title'
)
'test item 1'

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def ask_for_one_item(items, default=None, prompt=None, title=None, **kwargs):
    """Ask user to select an item from a list of items.

    This is a shortcut function that configures :obj:`GetValueWindow` for
    'single-select' data types. kwargs can be used to pass on other arguments.

    Args:
        items (list[str]): list of items to choose from
        default (str): default selected item
        prompt (str): prompt message
        title (str): title message
        kwargs (type): other arguments to be passed to :obj:`GetValueWindow`

    Returns:
        (str): selected item

    Examples:
        ```python
        forms.ask_for_one_item(
            ['test item 1', 'test item 2', 'test item 3'],
            default='test item 2',
            prompt='test prompt',
            title='test title'
        )
        'test item 1'
        ```
    """
    return GetValueWindow.show(
        items,
        value_type="dropdown",
        default=default,
        prompt=prompt,
        title=title,
        **kwargs
    )

ask_for_date(default=None, prompt=None, title=None, **kwargs)

Ask user to select a date value.

This is a shortcut function that configures :obj:GetValueWindow for date data types. kwargs can be used to pass on other arguments.

Parameters:

Name	Type	Description	Default
default	datetime	default selected date value	None
prompt	str	prompt message	None
title	str	title message	None
kwargs	type	other arguments to be passed to :obj:GetValueWindow	{}

Returns:

Type	Description
datetime	selected date

Examples:

forms.ask_for_date(default="", title="Enter deadline:")
datetime.datetime(2019, 5, 17, 0, 0)

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def ask_for_date(default=None, prompt=None, title=None, **kwargs):
    """Ask user to select a date value.

    This is a shortcut function that configures :obj:`GetValueWindow` for
    date data types. kwargs can be used to pass on other arguments.

    Args:
        default (datetime.datetime): default selected date value
        prompt (str): prompt message
        title (str): title message
        kwargs (type): other arguments to be passed to :obj:`GetValueWindow`

    Returns:
        (datetime.datetime): selected date

    Examples:
        ```python
        forms.ask_for_date(default="", title="Enter deadline:")
        datetime.datetime(2019, 5, 17, 0, 0)
        ```
    """
    return GetValueWindow.show(
        None, value_type="date", default=default, prompt=prompt, title=title, **kwargs
    )

ask_for_number_slider(default=None, min=0, max=100, interval=1, prompt=None, title=None, **kwargs)

Ask user to select a number value.

This is a shortcut function that configures :obj:GetValueWindow for numbers. kwargs can be used to pass on other arguments.

Parameters:

Name	Type	Description	Default
default	str	default unique string. must not be in reserved_values	None
min	int	minimum value on slider	0
max	int	maximum value on slider	100
interval	int	number interval between values	1
prompt	str	prompt message	None
title	str	title message	None
kwargs	type	other arguments to be passed to :obj:GetValueWindow	{}

Returns:

Type	Description
str	selected string value

Examples:

forms.ask_for_number_slider(
    default=50,
    min = 0,
    max = 100,
    interval = 5,
    prompt='Select a number:',
    title='test title')
'50'

In this example, the slider will allow values such as '40, 45, 50, 55, 60' etc

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def ask_for_number_slider(
    default=None, min=0, max=100, interval=1, prompt=None, title=None, **kwargs
):
    """Ask user to select a number value.

    This is a shortcut function that configures :obj:`GetValueWindow` for
    numbers. kwargs can be used to pass on other arguments.

    Args:
        default (str): default unique string. must not be in reserved_values
        min (int): minimum value on slider
        max (int): maximum value on slider
        interval (int): number interval between values
        prompt (str): prompt message
        title (str): title message
        kwargs (type): other arguments to be passed to :obj:`GetValueWindow`

    Returns:
        (str): selected string value

    Examples:
        ```python
        forms.ask_for_number_slider(
            default=50,
            min = 0,
            max = 100,
            interval = 5,
            prompt='Select a number:',
            title='test title')
        '50'
        ```

    In this example, the slider will allow values such as '40, 45, 50, 55, 60' etc
    """
    return GetValueWindow.show(
        None,
        value_type="slider",
        default=default,
        prompt=prompt,
        title=title,
        max=max,
        min=min,
        interval=interval,
        **kwargs
    )

ask_to_use_selected(type_name, count=None, multiple=True)

Ask user if wants to use currently selected elements.

Parameters:

Name	Type	Description	Default
type_name	str	Element type of expected selected elements	required
count	int	Number of selected items	None
multiple	bool	Whether multiple selected items are allowed	True

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def ask_to_use_selected(type_name, count=None, multiple=True):
    """Ask user if wants to use currently selected elements.

    Args:
        type_name (str): Element type of expected selected elements
        count (int): Number of selected items
        multiple (bool): Whether multiple selected items are allowed
    """
    report = type_name.lower()
    # multiple = True
    message = (
        "You currently have %s selected. Do you want to proceed with "
        "currently selected item(s)?"
    )
    # check is selecting multiple is allowd
    if not multiple:
        # multiple = False
        message = (
            "You currently have %s selected and only one is required. "
            "Do you want to use the first selected item?"
        )

    # check if count is provided
    if count is not None:
        report = "{} {}".format(count, report)
    return alert(message % report, yes=True, no=True)

ask_for_color(default=None)

Show system color picker and ask for color.

Parameters:

Name	Type	Description	Default
default	str	default color in HEX ARGB e.g. #ff808080	None

Returns:

Type	Description
str	selected color in HEX ARGB e.g. #ff808080, or None if cancelled

Examples:

forms.ask_for_color()
'#ff808080'

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def ask_for_color(default=None):
    """Show system color picker and ask for color.

    Args:
        default (str): default color in HEX ARGB e.g. #ff808080

    Returns:
        (str): selected color in HEX ARGB e.g. #ff808080, or None if cancelled

    Examples:
        ```python
        forms.ask_for_color()
        '#ff808080'
        ```
    """
    # colorDlg.Color
    color_picker = Forms.ColorDialog()
    if default:
        default = default.replace("#", "")
        color_picker.Color = System.Drawing.Color.FromArgb(
            int(default[:2], 16),
            int(default[2:4], 16),
            int(default[4:6], 16),
            int(default[6:8], 16),
        )
    color_picker.FullOpen = True
    if color_picker.ShowDialog() == Forms.DialogResult.OK:
        c = color_picker.Color
        c_hex = "".join("{:02X}".format(int(x)) for x in [c.A, c.R, c.G, c.B])
        return "#" + c_hex

inform_wip()

Show work-in-progress prompt to user and exit script.

Examples:

forms.inform_wip()

Source code in pyrevitlib/pyrevit/forms/_ipy.py

def inform_wip():
    """Show work-in-progress prompt to user and exit script.

    Examples:
        ```python
        forms.inform_wip()
        ```
    """
    alert("Work in progress.", exitscript=True)