forms
pyrevit.forms facade.
Imports the engine-specific forms backend for the active Python engine.
Attributes
HOST_APP = _HostApplication()
module-attribute
EXEC_PARAMS = _ExecutorParams()
module-attribute
DOCS = _DocsGetter()
module-attribute
BIN_DIR = op.join(ROOT_BIN_DIR, DOTNET_RUNTIME_ID)
module-attribute
safe_strtype = str
module-attribute
user_config = _build_user_config()
module-attribute
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
THEME_XAML_FILE = op.join(XAML_FILES_DIR, 'Theme.xaml')
module-attribute
Classes
PyRevitException
Bases: Exception
Common base class for all pyRevit exceptions.
Parameters args and message are derived from Exception class.
Attributes
msg
property
Return exception message.
reactive(getter)
Bases: property
Decorator for WPF bound properties.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Methods:
setter(setter)
Property setter.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Reactive
Bases: INotifyPropertyChanged
WPF property updator base mixin.
Methods:
add_PropertyChanged(value)
remove_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
WindowToggler(window)
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.
Use self.logger and self.output instead of using script.get_logger() and script.get_output()
to ensure correct titles in the output window.
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.
resolve_theme (bool):
resolve the palette from Revit's active UI theme. Defaults to False.
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
Attributes
pyrevit_version
property
Active pyRevit formatted version string, e.g. '4.9-beta'.
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
resolve_theme = False
class-attribute
instance-attribute
logger
property
Logger named after the panel, created on first access.
output
property
Output window with title corrected to panel_title whenever accessed.
Methods:
setup_resources(wpf_ctrl, set_root_colors=True, resolve_theme=False)
staticmethod
Set pyRevit colour resources on any WPF control.
Injects the brand palette (constant, used by HUD-style overlays) and the semantic light/dark palette as DynamicResource-able brushes. Theme resolution is opt-in so forms default to the light palette.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required | |
set_root_colors
|
bool
|
also force wpf_ctrl.Background/Foreground directly. Only safe before the control's own XAML is parsed: a window that declares its own literal Background (e.g. the transparent HUD-style overlays) must be able to override this afterwards. Live theme-change refreshes pass False so an already-open HUD window is not forced opaque. |
True
|
resolve_theme
|
bool
|
resolve the palette from Revit's active UI theme. Defaults to False. |
False
|
Note
The root colours are assigned directly rather than left to the implicit Window/Page style. The root element already exists before its Resources are populated, and its own implicit-style lookup does not reliably re-run once the brushes and Theme.xaml are merged afterwards, even though descendants created later during XAML parsing do pick the styles up.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_theme(wpf_ctrl)
staticmethod
Re-resolve and re-apply theme resources on an already-loaded control.
Because window/control chrome binds to these resources with DynamicResource, overwriting the values here is enough to repaint an open window without reloading its XAML. Does not touch the root Background/Foreground directly — see _live_refresh_root_colors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_contrast_foregrounds()
Give every custom-background element a readable text color.
Walks the logical tree and, for each element painting a background that is not one of the theme's own brushes, assigns whichever of the theme window foreground/background colors contrasts better with it. This keeps hardcoded accent colors in user XAML -- a pale red "danger" button, a pale green "confirm" button -- legible under a dark UI theme, where the inherited near-white text would otherwise vanish into them.
Elements that declare their own Foreground are left untouched, and so are theme-brush backgrounds, which already pair with the theme foreground. Translucent backgrounds are left untouched because their effective color depends on the surface below them. Contrast is supplied by a style setter so disabled-state triggers remain authoritative, including when IsEnabled changes after the window opens. Safe to call again after a theme change; unchanged brushes reuse the managed style. Previously managed elements that stop qualifying regain their original style, unless a local Foreground has been authored. Detached elements are dropped from tracking on the next pass, and a failed element does not prevent the remaining controls from updating.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 | |
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
get_locale_string(string_name, default=None)
Return a localised string from the merged ResourceDictionary.
Missing keys are treated as recoverable UI state: they are logged and a safe fallback is returned so the form can keep working without surfacing a blocking WPF exception dialog.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
string_name
|
str
|
resource key. |
required |
default
|
any
|
fallback value when the resource is missing. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
localised string value or the provided fallback. |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
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
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
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
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
disable_element(*wpf_elements)
staticmethod
Disable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to disable. |
()
|
enable_element(*wpf_elements)
staticmethod
Enable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to enable. |
()
|
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
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
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
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
Attributes
item = orig_item
instance-attribute
state = checked
instance-attribute
name
property
Name property.
checkable
property
writable
List Item CheckBox Visibility.
Methods:
add_PropertyChanged(value)
remove_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
unwrap()
ParamDef(name, istype, definition, isreadonly, isunit, storagetype, displayvalue, hasvalue, grouptype, isshared, paramid, checked=False)
Bases: TemplateListItem
Parameter definition for :func:select_parameters.
Inherits from :obj:TemplateListItem for use with SelectFromList.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
parameter name |
istype |
bool
|
true if type parameter, otherwise false |
definition |
Definition
|
parameter definition object |
isreadonly |
bool
|
true if the parameter value can't be edited |
isunit |
bool
|
true if its ForgeTypeId is measurable |
storagetype |
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) |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Attributes
item = orig_item
instance-attribute
state = checked
instance-attribute
checkable
property
writable
List Item CheckBox Visibility.
istype = istype
instance-attribute
definition = definition
instance-attribute
isreadonly = isreadonly
instance-attribute
isunit = isunit
instance-attribute
storagetype = storagetype
instance-attribute
displayvalue = displayvalue
instance-attribute
hasvalue = hasvalue
instance-attribute
grouptype = grouptype
instance-attribute
isshared = isshared
instance-attribute
paramid = paramid
instance-attribute
name
property
Parameter name.
Methods:
add_PropertyChanged(value)
remove_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
checked(value)
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
Attributes
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
xaml_source = 'GetValueWindow.xaml'
class-attribute
instance-attribute
resolve_theme = True
class-attribute
instance-attribute
Methods:
setup_resources(wpf_ctrl, set_root_colors=True, resolve_theme=False)
staticmethod
Set pyRevit colour resources on any WPF control.
Injects the brand palette (constant, used by HUD-style overlays) and the semantic light/dark palette as DynamicResource-able brushes. Theme resolution is opt-in so forms default to the light palette.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required | |
set_root_colors
|
bool
|
also force wpf_ctrl.Background/Foreground directly. Only safe before the control's own XAML is parsed: a window that declares its own literal Background (e.g. the transparent HUD-style overlays) must be able to override this afterwards. Live theme-change refreshes pass False so an already-open HUD window is not forced opaque. |
True
|
resolve_theme
|
bool
|
resolve the palette from Revit's active UI theme. Defaults to False. |
False
|
Note
The root colours are assigned directly rather than left to the implicit Window/Page style. The root element already exists before its Resources are populated, and its own implicit-style lookup does not reliably re-run once the brushes and Theme.xaml are merged afterwards, even though descendants created later during XAML parsing do pick the styles up.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_theme(wpf_ctrl)
staticmethod
Re-resolve and re-apply theme resources on an already-loaded control.
Because window/control chrome binds to these resources with DynamicResource, overwriting the values here is enough to repaint an open window without reloading its XAML. Does not touch the root Background/Foreground directly — see _live_refresh_root_colors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_contrast_foregrounds()
Give every custom-background element a readable text color.
Walks the logical tree and, for each element painting a background that is not one of the theme's own brushes, assigns whichever of the theme window foreground/background colors contrasts better with it. This keeps hardcoded accent colors in user XAML -- a pale red "danger" button, a pale green "confirm" button -- legible under a dark UI theme, where the inherited near-white text would otherwise vanish into them.
Elements that declare their own Foreground are left untouched, and so are theme-brush backgrounds, which already pair with the theme foreground. Translucent backgrounds are left untouched because their effective color depends on the surface below them. Contrast is supplied by a style setter so disabled-state triggers remain authoritative, including when IsEnabled changes after the window opens. Safe to call again after a theme change; unchanged brushes reuse the managed style. Previously managed elements that stop qualifying regain their original style, unless a local Foreground has been authored. Detached elements are dropped from tracking on the next pass, and a failed element does not prevent the remaining controls from updating.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 | |
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
get_locale_string(string_name, default=None)
Return a localised string from the merged ResourceDictionary.
Missing keys are treated as recoverable UI state: they are logged and a safe fallback is returned so the form can keep working without surfacing a blocking WPF exception dialog.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
string_name
|
str
|
resource key. |
required |
default
|
any
|
fallback value when the resource is missing. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
localised string value or the provided fallback. |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
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
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
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
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
disable_element(*wpf_elements)
staticmethod
Disable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to disable. |
()
|
enable_element(*wpf_elements)
staticmethod
Enable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to enable. |
()
|
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
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
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 |
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
setup_owner()
setup_default_handlers()
handle_input_key(sender, args)
set_icon(icon_path)
setup_icon()
Setup default window icon, following the bundle icon convention.
If required, picks up pyrevit_settings.dark.png under a dark UI theme,
the same
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
show_dialog()
conceal()
string_value_changed(sender, args)
Handle string vlaue update event.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
select(sender, args)
Process input data and set the response.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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: |
{}
|
Initialize user prompt window.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Attributes
pyrevit_version
property
Active pyRevit formatted version string, e.g. '4.9-beta'.
resolve_theme = False
class-attribute
instance-attribute
xaml_source = 'TemplatePromptBar.xaml'
class-attribute
instance-attribute
user_height = height
instance-attribute
Methods:
setup_resources(wpf_ctrl, set_root_colors=True, resolve_theme=False)
staticmethod
Set pyRevit colour resources on any WPF control.
Injects the brand palette (constant, used by HUD-style overlays) and the semantic light/dark palette as DynamicResource-able brushes. Theme resolution is opt-in so forms default to the light palette.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required | |
set_root_colors
|
bool
|
also force wpf_ctrl.Background/Foreground directly. Only safe before the control's own XAML is parsed: a window that declares its own literal Background (e.g. the transparent HUD-style overlays) must be able to override this afterwards. Live theme-change refreshes pass False so an already-open HUD window is not forced opaque. |
True
|
resolve_theme
|
bool
|
resolve the palette from Revit's active UI theme. Defaults to False. |
False
|
Note
The root colours are assigned directly rather than left to the implicit Window/Page style. The root element already exists before its Resources are populated, and its own implicit-style lookup does not reliably re-run once the brushes and Theme.xaml are merged afterwards, even though descendants created later during XAML parsing do pick the styles up.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_theme(wpf_ctrl)
staticmethod
Re-resolve and re-apply theme resources on an already-loaded control.
Because window/control chrome binds to these resources with DynamicResource, overwriting the values here is enough to repaint an open window without reloading its XAML. Does not touch the root Background/Foreground directly — see _live_refresh_root_colors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_contrast_foregrounds()
Give every custom-background element a readable text color.
Walks the logical tree and, for each element painting a background that is not one of the theme's own brushes, assigns whichever of the theme window foreground/background colors contrasts better with it. This keeps hardcoded accent colors in user XAML -- a pale red "danger" button, a pale green "confirm" button -- legible under a dark UI theme, where the inherited near-white text would otherwise vanish into them.
Elements that declare their own Foreground are left untouched, and so are theme-brush backgrounds, which already pair with the theme foreground. Translucent backgrounds are left untouched because their effective color depends on the surface below them. Contrast is supplied by a style setter so disabled-state triggers remain authoritative, including when IsEnabled changes after the window opens. Safe to call again after a theme change; unchanged brushes reuse the managed style. Previously managed elements that stop qualifying regain their original style, unless a local Foreground has been authored. Detached elements are dropped from tracking on the next pass, and a failed element does not prevent the remaining controls from updating.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 | |
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
get_locale_string(string_name, default=None)
Return a localised string from the merged ResourceDictionary.
Missing keys are treated as recoverable UI state: they are logged and a safe fallback is returned so the form can keep working without surfacing a blocking WPF exception dialog.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
string_name
|
str
|
resource key. |
required |
default
|
any
|
fallback value when the resource is missing. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
localised string value or the provided fallback. |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
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
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
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
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
disable_element(*wpf_elements)
staticmethod
Disable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to disable. |
()
|
enable_element(*wpf_elements)
staticmethod
Enable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to enable. |
()
|
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
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
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 |
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
setup_owner()
setup_default_handlers()
handle_input_key(sender, args)
set_icon(icon_path)
setup_icon()
Setup default window icon, following the bundle icon convention.
If required, picks up pyrevit_settings.dark.png under a dark UI theme,
the same
Source code in pyrevitlib/pyrevit/forms/_ipy.py
hide()
show(modal=False)
show_dialog()
conceal()
update_window()
Update the prompt bar to match Revit window.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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:
Initialize user prompt window.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Attributes
pyrevit_version
property
Active pyRevit formatted version string, e.g. '4.9-beta'.
resolve_theme = False
class-attribute
instance-attribute
user_height = height
instance-attribute
xaml_source = 'WarningBar.xaml'
class-attribute
instance-attribute
Methods:
setup_resources(wpf_ctrl, set_root_colors=True, resolve_theme=False)
staticmethod
Set pyRevit colour resources on any WPF control.
Injects the brand palette (constant, used by HUD-style overlays) and the semantic light/dark palette as DynamicResource-able brushes. Theme resolution is opt-in so forms default to the light palette.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required | |
set_root_colors
|
bool
|
also force wpf_ctrl.Background/Foreground directly. Only safe before the control's own XAML is parsed: a window that declares its own literal Background (e.g. the transparent HUD-style overlays) must be able to override this afterwards. Live theme-change refreshes pass False so an already-open HUD window is not forced opaque. |
True
|
resolve_theme
|
bool
|
resolve the palette from Revit's active UI theme. Defaults to False. |
False
|
Note
The root colours are assigned directly rather than left to the implicit Window/Page style. The root element already exists before its Resources are populated, and its own implicit-style lookup does not reliably re-run once the brushes and Theme.xaml are merged afterwards, even though descendants created later during XAML parsing do pick the styles up.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_theme(wpf_ctrl)
staticmethod
Re-resolve and re-apply theme resources on an already-loaded control.
Because window/control chrome binds to these resources with DynamicResource, overwriting the values here is enough to repaint an open window without reloading its XAML. Does not touch the root Background/Foreground directly — see _live_refresh_root_colors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_contrast_foregrounds()
Give every custom-background element a readable text color.
Walks the logical tree and, for each element painting a background that is not one of the theme's own brushes, assigns whichever of the theme window foreground/background colors contrasts better with it. This keeps hardcoded accent colors in user XAML -- a pale red "danger" button, a pale green "confirm" button -- legible under a dark UI theme, where the inherited near-white text would otherwise vanish into them.
Elements that declare their own Foreground are left untouched, and so are theme-brush backgrounds, which already pair with the theme foreground. Translucent backgrounds are left untouched because their effective color depends on the surface below them. Contrast is supplied by a style setter so disabled-state triggers remain authoritative, including when IsEnabled changes after the window opens. Safe to call again after a theme change; unchanged brushes reuse the managed style. Previously managed elements that stop qualifying regain their original style, unless a local Foreground has been authored. Detached elements are dropped from tracking on the next pass, and a failed element does not prevent the remaining controls from updating.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 | |
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
get_locale_string(string_name, default=None)
Return a localised string from the merged ResourceDictionary.
Missing keys are treated as recoverable UI state: they are logged and a safe fallback is returned so the form can keep working without surfacing a blocking WPF exception dialog.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
string_name
|
str
|
resource key. |
required |
default
|
any
|
fallback value when the resource is missing. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
localised string value or the provided fallback. |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
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
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
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
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
disable_element(*wpf_elements)
staticmethod
Disable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to disable. |
()
|
enable_element(*wpf_elements)
staticmethod
Enable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to enable. |
()
|
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
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
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 |
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
setup_owner()
setup_default_handlers()
handle_input_key(sender, args)
set_icon(icon_path)
setup_icon()
Setup default window icon, following the bundle icon convention.
If required, picks up pyrevit_settings.dark.png under a dark UI theme,
the same
Source code in pyrevitlib/pyrevit/forms/_ipy.py
hide()
show(modal=False)
show_dialog()
conceal()
update_window()
Update the prompt bar to match Revit window.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
Attributes
pyrevit_version
property
Active pyRevit formatted version string, e.g. '4.9-beta'.
resolve_theme = False
class-attribute
instance-attribute
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.
Methods:
setup_resources(wpf_ctrl, set_root_colors=True, resolve_theme=False)
staticmethod
Set pyRevit colour resources on any WPF control.
Injects the brand palette (constant, used by HUD-style overlays) and the semantic light/dark palette as DynamicResource-able brushes. Theme resolution is opt-in so forms default to the light palette.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required | |
set_root_colors
|
bool
|
also force wpf_ctrl.Background/Foreground directly. Only safe before the control's own XAML is parsed: a window that declares its own literal Background (e.g. the transparent HUD-style overlays) must be able to override this afterwards. Live theme-change refreshes pass False so an already-open HUD window is not forced opaque. |
True
|
resolve_theme
|
bool
|
resolve the palette from Revit's active UI theme. Defaults to False. |
False
|
Note
The root colours are assigned directly rather than left to the implicit Window/Page style. The root element already exists before its Resources are populated, and its own implicit-style lookup does not reliably re-run once the brushes and Theme.xaml are merged afterwards, even though descendants created later during XAML parsing do pick the styles up.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_theme(wpf_ctrl)
staticmethod
Re-resolve and re-apply theme resources on an already-loaded control.
Because window/control chrome binds to these resources with DynamicResource, overwriting the values here is enough to repaint an open window without reloading its XAML. Does not touch the root Background/Foreground directly — see _live_refresh_root_colors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
wpf_ctrl
|
any WPF FrameworkElement with a Resources dict. |
required |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
apply_contrast_foregrounds()
Give every custom-background element a readable text color.
Walks the logical tree and, for each element painting a background that is not one of the theme's own brushes, assigns whichever of the theme window foreground/background colors contrasts better with it. This keeps hardcoded accent colors in user XAML -- a pale red "danger" button, a pale green "confirm" button -- legible under a dark UI theme, where the inherited near-white text would otherwise vanish into them.
Elements that declare their own Foreground are left untouched, and so are theme-brush backgrounds, which already pair with the theme foreground. Translucent backgrounds are left untouched because their effective color depends on the surface below them. Contrast is supplied by a style setter so disabled-state triggers remain authoritative, including when IsEnabled changes after the window opens. Safe to call again after a theme change; unchanged brushes reuse the managed style. Previously managed elements that stop qualifying regain their original style, unless a local Foreground has been authored. Detached elements are dropped from tracking on the next pass, and a failed element does not prevent the remaining controls from updating.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 | |
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
get_locale_string(string_name, default=None)
Return a localised string from the merged ResourceDictionary.
Missing keys are treated as recoverable UI state: they are logged and a safe fallback is returned so the form can keep working without surfacing a blocking WPF exception dialog.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
string_name
|
str
|
resource key. |
required |
default
|
any
|
fallback value when the resource is missing. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
localised string value or the provided fallback. |
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
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
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
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
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
disable_element(*wpf_elements)
staticmethod
Disable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to disable. |
()
|
enable_element(*wpf_elements)
staticmethod
Enable one or more WPF elements.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*wpf_elements
|
list[UIElement]
|
elements to enable. |
()
|
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
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
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 |
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
setup_owner()
setup_default_handlers()
handle_input_key(sender, args)
set_icon(icon_path)
setup_icon()
Setup default window icon, following the bundle icon convention.
If required, picks up pyrevit_settings.dark.png under a dark UI theme,
the same
Source code in pyrevitlib/pyrevit/forms/_ipy.py
hide()
show_dialog()
conceal()
update_results_display(fill_match=False)
Update search prompt results based on current input text.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
set_search_results(*args)
Set search results for returning.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
find_direct_match(input_text)
Find direct text matches in search term.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
find_word_match(input_text)
Find direct word matches in search term.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
search_txt_changed(sender, args)
Handle text changed event.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
handle_kb_key(sender, args)
Handle keyboard input event.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
show(search_db, width=DEFAULT_SEARCHWND_WIDTH, height=DEFAULT_SEARCHWND_HEIGHT, **kwargs)
classmethod
Show search prompt.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
RevisionOption(revision_element)
Bases: TemplateListItem
Revision wrapper for :func:select_revisions.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Attributes
item = orig_item
instance-attribute
state = checked
instance-attribute
checkable
property
writable
List Item CheckBox Visibility.
name
property
Revision name (description).
Methods:
add_PropertyChanged(value)
remove_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
unwrap()
SheetOption(sheet_element)
Bases: TemplateListItem
Sheet wrapper for :func:select_sheets.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Attributes
item = orig_item
instance-attribute
state = checked
instance-attribute
checkable
property
writable
List Item CheckBox Visibility.
name
property
Sheet name.
number
property
Sheet number.
Methods:
add_PropertyChanged(value)
remove_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
unwrap()
ViewOption(view_element)
Bases: TemplateListItem
View wrapper for :func:select_views.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Attributes
item = orig_item
instance-attribute
state = checked
instance-attribute
checkable
property
writable
List Item CheckBox Visibility.
name
property
View name.
Methods:
add_PropertyChanged(value)
remove_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
unwrap()
LevelOption(level_element)
Bases: TemplateListItem
Level wrapper for :func:select_levels.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Attributes
item = orig_item
instance-attribute
state = checked
instance-attribute
checkable
property
writable
List Item CheckBox Visibility.
name
property
Level name.
Methods:
add_PropertyChanged(value)
remove_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
unwrap()
FamilyParamOption(fparam, builtin=False, labeled=False, associated=False, checked=False)
Bases: TemplateListItem
Level wrapper for :func:select_family_parameters.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
Attributes
item = orig_item
instance-attribute
state = checked
instance-attribute
checkable
property
writable
List Item CheckBox Visibility.
isbuiltin = builtin
instance-attribute
islabeled = labeled
instance-attribute
isassociated = associated
instance-attribute
name
property
Family Parameter name.
istype
property
Is type parameter.
Methods:
add_PropertyChanged(value)
remove_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
unwrap()
WPFWindow(*args, **kwargs)
TemplateUserInputWindow(*args, **kwargs)
Bases: WPFWindow
Source code in pyrevitlib/pyrevit/forms/_cpy.py
SelectFromList(*args, **kwargs)
Bases: TemplateUserInputWindow
Source code in pyrevitlib/pyrevit/forms/_cpy.py
CommandSwitchWindow(*args, **kwargs)
Bases: TemplateUserInputWindow
Source code in pyrevitlib/pyrevit/forms/_cpy.py
ProgressBar(*args, **kwargs)
Functions:
get_elementid_value_func()
Returns the ElementId value extraction function based on the Revit version.
Follows API changes in Revit 2024.
Returns:
| Name | Type | Description |
|---|---|---|
function |
A function returns the value of an ElementId. |
Examples:
get_elementid_value = get_elementid_value_func()
sheet_revids = {get_elementid_value(x) for x in self.revit_sheet.GetAllRevisionIds()}
add_sheet_revids = {get_elementid_value(x) for x in self.revit_sheet.GetAdditionalRevisionIds()}
Source code in pyrevitlib/pyrevit/compat.py
get_logger(logger_name)
Return the cached runtime-backed facade for logger_name.
Source code in pyrevitlib/pyrevit/coreutils/logger.py
is_dark_theme()
Return True if Revit's active UI theme is Dark.
Always False on Revit <2024, which has no UITheme concept.
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
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
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
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 |
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 |
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
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
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
3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 | |
select_views(title='Select Views', button_name='Select', width=DEFAULT_INPUTWINDOW_WIDTH, multiple=True, filterfunc=None, doc=None, use_selection=False, group_by_view_type=True)
Standard form for selecting views.
Views are grouped by view type and the type can be selected from a drop down box at the top of window. Type names are localized using Revit's own labels.
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
|
group_by_view_type
|
bool
|
show a view type drop down with an "All Views" entry first. Defaults to True |
True
|
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
3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 | |
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
3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 | |
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
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
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
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
select_parameters(src_element, title='Select Parameters', button_name='Select', multiple=True, filterfunc=None, include_instance=True, include_type=True, exclude_readonly=True, preselect=None)
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
|
preselect
|
list[ParamDef | str]
|
list of ParamDef objects or parameter name strings to pre-check |
None
|
Returns:
| Type | Description |
|---|---|
list[ParamDef]
|
list of paramdef objects |
Examples:
forms.select_parameters(
src_element,
title='Select Parameters',
multiple=True,
include_instance=True,
include_type=True
)
[<ParamDef >, <ParamDef >]
Source code in pyrevitlib/pyrevit/forms/_ipy.py
3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 | |
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, preselect=None)
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
|
preselect
|
list[FamilyParamOption | str]
|
list of FamilyParamOption objects or parameter name strings to pre-check |
None
|
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
)
[<FamilyParamOption >, <FamilyParamOption >]
Source code in pyrevitlib/pyrevit/forms/_ipy.py
3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 | |
alert(msg, title=None, sub_msg=None, expanded=None, footer='', ok=True, cancel=False, yes=False, no=False, retry=False, warn_icon=True, icon='', 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. Ignored if |
True
|
icon
|
str
|
icon to show, from one of "warning", "shield", "information", "error".
When provided (non-empty), this takes full precedence over |
''
|
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
3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 | |
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
result_item_result_clicked(sender, e, debug=False)
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
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 |
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
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
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
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
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
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:
Source code in pyrevitlib/pyrevit/forms/_ipy.py
inform_wip()
Show work-in-progress prompt to user and exit script.
Examples: