Skip to content

forms

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

Parameter definition tuple.

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

Classes

reactive(getter)

Bases: property

Decorator for WPF bound properties.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
87
88
89
90
91
92
93
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/__init__.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
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/__init__.py 
113
114
115
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/__init__.py 
117
118
119
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/__init__.py 
121
122
123
124
125
126
127
128
129
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/__init__.py 
134
135
def __init__(self, window):
    self._window = window

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

Bases: 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/__init__.py 
168
169
170
171
172
173
174
175
176
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 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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
306
307
308
309
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show(modal=False)

Show window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
323
324
325
326
327
328
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/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)

WPFPanel()

Bases: Page

WPF panel base class for all pyRevit dockable panels.

panel_id (str) must be set on the type to dockable panel uuid panel_source (str): xaml source filepath

Examples:

from pyrevit import forms
class MyPanel(forms.WPFPanel):
    panel_id = "181e05a4-28f6-4311-8a9f-d2aa528c8755"
    panel_source = "MyPanel.xaml"

forms.register_dockable_panel(MyPanel)
# then from the button that needs to open the panel
forms.open_dockable_panel("181e05a4-28f6-4311-8a9f-d2aa528c8755")

Initialize WPF panel and resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
def __init__(self):
    """Initialize WPF panel and resources."""
    if not self.panel_id:
        raise PyRevitException("\"panel_id\" property is not set")
    if not self.panel_source:
        raise PyRevitException("\"panel_source\" property is not set")

    if not op.exists(self.panel_source):
        wpf.LoadComponent(self,
                          os.path.join(EXEC_PARAMS.command_path,
                          self.panel_source))
    else:
        wpf.LoadComponent(self, self.panel_source)

    # set properties
    self.thread_id = framework.get_current_thread_id()
    WPFWindow.setup_resources(self)

Attributes

panel_id = None class-attribute instance-attribute
panel_source = None class-attribute instance-attribute
thread_id = framework.get_current_thread_id() instance-attribute

Functions

set_image_source(wpf_element, image_file)

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
493
494
495
496
497
498
499
500
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
502
503
504
505
506
507
508
509
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    WPFPanel.hide_element(*wpf_elements)
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
511
512
513
514
515
516
517
518
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    WPFPanel.show_element(*wpf_elements)
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
520
521
522
523
524
525
526
527
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    WPFPanel.toggle_element(*wpf_elements)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
529
530
531
532
533
534
535
536
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    WPFPanel.disable_element(*wpf_elements)
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
538
539
540
541
542
543
544
545
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list): WPF framework elements to be enabled
    """
    WPFPanel.enable_element(*wpf_elements)
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
547
548
549
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    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/__init__.py 
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
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)
    self.Title = title or 'pyRevit'
    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

pyrevit_version property

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

xaml_source = 'BaseWindow.xaml' class-attribute instance-attribute
Title = title or 'pyRevit' 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

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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
306
307
308
309
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)
show(context, title='User Input', 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

 'User Input'
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/__init__.py 
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
@classmethod
def show(cls, context,  #pylint: disable=W0221
         title='User Input',
         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

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/__init__.py 
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
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

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
113
114
115
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/__init__.py 
117
118
119
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/__init__.py 
121
122
123
124
125
126
127
128
129
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/__init__.py 
753
754
755
def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item
checked(value)
Source code in pyrevitlib/pyrevit/forms/__init__.py 
762
763
764
@checked.setter
def checked(self, value):
    self.state = value

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/__init__.py 
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
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)
    self.Title = title or 'pyRevit'
    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

pyrevit_version property

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

Title = title or 'pyRevit' 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
in_check = False class-attribute instance-attribute
in_uncheck = False class-attribute instance-attribute
xaml_source = 'SelectFromList.xaml' class-attribute instance-attribute
use_regex property

Is using regex?

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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
306
307
308
309
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show(context, title='User Input', 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

 'User Input'
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/__init__.py 
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
@classmethod
def show(cls, context,  #pylint: disable=W0221
         title='User Input',
         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/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)
toggle_all(sender, args)

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

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1091
1092
1093
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/__init__.py 
1095
1096
1097
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/__init__.py 
1099
1100
1101
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/__init__.py 
1103
1104
1105
1106
1107
1108
1109
1110
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/__init__.py 
1112
1113
1114
1115
1116
1117
1118
1119
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/__init__.py 
1121
1122
1123
1124
1125
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/__init__.py 
1127
1128
1129
1130
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/__init__.py 
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
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/__init__.py 
1144
1145
1146
1147
1148
1149
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/__init__.py 
1151
1152
1153
1154
1155
1156
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/__init__.py 
1158
1159
1160
1161
1162
1163
1164
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 box.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1166
1167
1168
1169
1170
def clear_search(self, sender, args):    #pylint: disable=W0613
    """Clear search box."""
    self.search_tb.Text = ' '
    self.search_tb.Clear()
    self.search_tb.Focus()

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/__init__.py 
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
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)
    self.Title = title or 'pyRevit'
    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

pyrevit_version property

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

Title = title or 'pyRevit' 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 = 'CommandSwitchWindow.xaml' class-attribute instance-attribute

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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show(context, title='User Input', 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

 'User Input'
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/__init__.py 
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
@classmethod
def show(cls, context,  #pylint: disable=W0221
         title='User Input',
         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/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)
handle_click(sender, args)

Handle mouse click.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1304
1305
1306
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/__init__.py 
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
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/__init__.py 
1329
1330
1331
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/__init__.py 
1333
1334
1335
1336
1337
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)

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/__init__.py 
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
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)
    self.Title = title or 'pyRevit'
    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

pyrevit_version property

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

Title = title or 'pyRevit' 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

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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
306
307
308
309
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show(context, title='User Input', 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

 'User Input'
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/__init__.py 
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
@classmethod
def show(cls, context,  #pylint: disable=W0221
         title='User Input',
         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/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)
string_value_changed(sender, args)

Handle string vlaue update event.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
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/__init__.py 
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
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:
            datestr = self.datePicker.SelectedDate.ToString("MM/dd/yyyy")
            self.response = datetime.datetime.strptime(datestr, r'%m/%d/%Y')
        else:
            self.response = None
    elif self.value_type == 'slider':
        self.response = self.numberPicker.Value

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/__init__.py 
1443
1444
1445
1446
1447
1448
1449
1450
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

pyrevit_version property

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

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

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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
306
307
308
309
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show(modal=False)

Show window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
323
324
325
326
327
328
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/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)
update_window()

Update the prompt bar to match Revit window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
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

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

Examples:

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

Initialize user prompt window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1443
1444
1445
1446
1447
1448
1449
1450
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

pyrevit_version property

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

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

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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
306
307
308
309
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show(modal=False)

Show window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
323
324
325
326
327
328
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/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)
update_window()

Update the prompt bar to match Revit window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
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/__init__.py 
1443
1444
1445
1446
1447
1448
1449
1450
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

pyrevit_version property

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

user_height = height instance-attribute
xaml_source = 'ProgressBar.xaml' class-attribute instance-attribute
title property writable

Progress bar title.

indeterminate property writable

Progress bar indeterminate state.

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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
306
307
308
309
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show(modal=False)

Show window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
323
324
325
326
327
328
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/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)
update_window()

Update the prompt bar to match Revit window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
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
clicked_cancel(sender, args)

Handler for cancel button clicked event.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1674
1675
1676
1677
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/__init__.py 
1679
1680
1681
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/__init__.py 
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
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()

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/__init__.py 
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
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

pyrevit_version property

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

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.

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 se the window owner. Defaults to True.

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
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 se the window owner.
            Defaults to True.
    """
    # create new id for this window
    self.window_id = coreutils.new_uuid()

    if not literal_string:
        wpf.LoadComponent(self, self._determine_xaml(xaml_source))
    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()
    WPFWindow.setup_resources(self)
    if handle_esc:
        self.setup_default_handlers()
merge_resource_dict(xaml_source)

Merge a ResourceDictionary xaml file with this window.

Parameters:

Name Type Description Default
xaml_source str

xaml file with the resource dictionary

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
243
244
245
246
247
248
249
250
251
def merge_resource_dict(self, xaml_source):
    """Merge a ResourceDictionary xaml file with this window.

    Args:
        xaml_source (str): xaml file with the resource dictionary
    """
    lang_dictionary = ResourceDictionary()
    lang_dictionary.Source = Uri(xaml_source, UriKind.Absolute)
    self.Resources.MergedDictionaries.Add(lang_dictionary)
get_locale_string(string_name)

Get localized string.

Parameters:

Name Type Description Default
string_name str

string name

 required

Returns:

Type Description
str

localized string
Source code in pyrevitlib/pyrevit/forms/__init__.py 
253
254
255
256
257
258
259
260
261
262
def get_locale_string(self, string_name):
    """Get localized string.

    Args:
        string_name (str): string name

    Returns:
        (str): localized string
    """
    return self.FindResource(string_name)
setup_owner()

Set the window owner.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
264
265
266
267
def setup_owner(self):
    """Set the window owner."""
    wih = Interop.WindowInteropHelper(self)
    wih.Owner = AdWindows.ComponentManager.ApplicationWindow
setup_resources(wpf_ctrl) staticmethod

Sets the WPF resources.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
@staticmethod
def setup_resources(wpf_ctrl):
    """Sets the WPF resources."""
    #2c3e50
    wpf_ctrl.Resources['pyRevitDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x2c, 0x3e, 0x50)

    #23303d
    wpf_ctrl.Resources['pyRevitDarkerDarkColor'] = \
        Media.Color.FromArgb(0xFF, 0x23, 0x30, 0x3d)

    #ffffff
    wpf_ctrl.Resources['pyRevitButtonColor'] = \
        Media.Color.FromArgb(0xFF, 0xff, 0xff, 0xff)

    #f39c12
    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
setup_default_handlers()

Set the default handlers.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
302
303
304
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/__init__.py 
306
307
308
309
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/__init__.py 
311
312
313
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/__init__.py 
315
316
317
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/__init__.py 
319
320
321
def hide(self):
    """Hide window."""
    self.Hide()
show_dialog()

Show modal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
330
331
332
def show_dialog(self):
    """Show modal window."""
    return self.ShowDialog()
set_image_source_file(wpf_element, image_file) staticmethod

Set source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@staticmethod
def set_image_source_file(wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file 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 source file for image element.

Parameters:

Name Type Description Default
wpf_element Image

xaml image element

 required
image_file str

image file path

 required
Source code in pyrevitlib/pyrevit/forms/__init__.py 
351
352
353
354
355
356
357
358
def set_image_source(self, wpf_element, image_file):
    """Set source file for image element.

    Args:
        wpf_element (System.Windows.Controls.Image): xaml image element
        image_file (str): image file path
    """
    WPFWindow.set_image_source_file(wpf_element, image_file)
dispatch(func, *args, **kwargs)

Runs the function in a new thread.

Parameters:

Name Type Description Default
func Callable

function to run

 required
*args Any

positional arguments to pass to func

 ()
**kwargs Any

keyword arguments to pass to func

 {}
Source code in pyrevitlib/pyrevit/forms/__init__.py 
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def dispatch(self, func, *args, **kwargs):
    """Runs the function in a new thread.

    Args:
        func (Callable): function to run
        *args (Any): positional arguments to pass to func
        **kwargs (Any): keyword arguments to pass to func
    """
    if framework.get_current_thread_id() == self.thread_id:
        t = threading.Thread(
            target=func,
            args=args,
            kwargs=kwargs
            )
        t.start()
    else:
        # ask ui thread to call the func with args and kwargs
        self.Dispatcher.Invoke(
            System.Action(
                lambda: func(*args, **kwargs)
                ),
            Threading.DispatcherPriority.Background
            )
conceal()

Conceal window.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
384
385
386
def conceal(self):
    """Conceal window."""
    return WindowToggler(self)
hide_element(*wpf_elements) staticmethod

Collapse elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be collaped

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
395
396
397
398
399
400
401
402
403
@staticmethod
def hide_element(*wpf_elements):
    """Collapse elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be collaped
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_COLLAPSED
show_element(*wpf_elements) staticmethod

Show collapsed elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be set to visible.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
405
406
407
408
409
410
411
412
413
@staticmethod
def show_element(*wpf_elements):
    """Show collapsed elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be set to visible.
    """
    for wpfel in wpf_elements:
        wpfel.Visibility = WPF_VISIBLE
toggle_element(*wpf_elements) staticmethod

Toggle visibility of elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be toggled.

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
415
416
417
418
419
420
421
422
423
424
425
426
@staticmethod
def toggle_element(*wpf_elements):
    """Toggle visibility of elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be toggled.
    """
    for wpfel in wpf_elements:
        if wpfel.Visibility == WPF_VISIBLE:
            WPFWindow.hide_element(wpfel)
        elif wpfel.Visibility == WPF_COLLAPSED:
            WPFWindow.show_element(wpfel)
disable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
428
429
430
431
432
433
434
435
436
@staticmethod
def disable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = False
enable_element(*wpf_elements) staticmethod

Enable elements.

Parameters:

Name Type Description Default
*wpf_elements list[UIElement]

WPF framework elements to be enabled

 ()
Source code in pyrevitlib/pyrevit/forms/__init__.py 
438
439
440
441
442
443
444
445
446
@staticmethod
def enable_element(*wpf_elements):
    """Enable elements.

    Args:
        *wpf_elements (list[UIElement]): WPF framework elements to be enabled
    """
    for wpfel in wpf_elements:
        wpfel.IsEnabled = True
handle_url_click(sender, args)

Callback for handling click on package website url.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
448
449
450
def handle_url_click(self, sender, args): #pylint: disable=unused-argument
    """Callback for handling click on package website url."""
    return webbrowser.open_new_tab(sender.NavigateUri.AbsoluteUri)
update_results_display(fill_match=False)

Update search prompt results based on current input text.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
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/__init__.py 
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
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/__init__.py 
1903
1904
1905
1906
1907
1908
1909
1910
1911
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/__init__.py 
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
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/__init__.py 
1924
1925
1926
1927
1928
1929
1930
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/__init__.py 
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
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/__init__.py 
1965
1966
1967
1968
1969
1970
1971
1972
@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

RevisionOption(revision_element)

Bases: TemplateListItem

Revision wrapper for :func:select_revisions.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
1977
1978
def __init__(self, revision_element):
    super(RevisionOption, self).__init__(revision_element)

Attributes

item = orig_item instance-attribute
state = checked instance-attribute
checkable property writable

List Item CheckBox Visibility.

name property

Revision name (description).

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
113
114
115
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/__init__.py 
117
118
119
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/__init__.py 
121
122
123
124
125
126
127
128
129
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/__init__.py 
753
754
755
def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item
checked(value)
Source code in pyrevitlib/pyrevit/forms/__init__.py 
762
763
764
@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/__init__.py 
1996
1997
def __init__(self, sheet_element):
    super(SheetOption, self).__init__(sheet_element)

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.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
113
114
115
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/__init__.py 
117
118
119
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/__init__.py 
121
122
123
124
125
126
127
128
129
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/__init__.py 
753
754
755
def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item
checked(value)
Source code in pyrevitlib/pyrevit/forms/__init__.py 
762
763
764
@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/__init__.py 
2015
2016
def __init__(self, view_element):
    super(ViewOption, self).__init__(view_element)

Attributes

item = orig_item instance-attribute
state = checked instance-attribute
checkable property writable

List Item CheckBox Visibility.

name property

View name.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
113
114
115
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/__init__.py 
117
118
119
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/__init__.py 
121
122
123
124
125
126
127
128
129
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/__init__.py 
753
754
755
def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item
checked(value)
Source code in pyrevitlib/pyrevit/forms/__init__.py 
762
763
764
@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/__init__.py 
2027
2028
def __init__(self, level_element):
    super(LevelOption, self).__init__(level_element)

Attributes

item = orig_item instance-attribute
state = checked instance-attribute
checkable property writable

List Item CheckBox Visibility.

name property

Level name.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
113
114
115
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/__init__.py 
117
118
119
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/__init__.py 
121
122
123
124
125
126
127
128
129
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/__init__.py 
753
754
755
def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item
checked(value)
Source code in pyrevitlib/pyrevit/forms/__init__.py 
762
763
764
@checked.setter
def checked(self, value):
    self.state = value

FamilyParamOption(fparam, builtin=False, labeled=False)

Bases: TemplateListItem

Level wrapper for :func:select_family_parameters.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
2038
2039
2040
2041
def __init__(self, fparam, builtin=False, labeled=False):
    super(FamilyParamOption, self).__init__(fparam)
    self.isbuiltin = builtin
    self.islabeled = labeled

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
name property

Family Parameter name.

istype property

Is type parameter.

Functions

add_PropertyChanged(value)

Called when a property is added to the object.

Source code in pyrevitlib/pyrevit/forms/__init__.py 
113
114
115
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/__init__.py 
117
118
119
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/__init__.py 
121
122
123
124
125
126
127
128
129
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/__init__.py 
753
754
755
def unwrap(self):
    """Unwrap and return wrapped object."""
    return self.item
checked(value)
Source code in pyrevitlib/pyrevit/forms/__init__.py 
762
763
764
@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/__init__.py 
568
569
570
571
572
573
574
575
576
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.PaneExists(dockable_panel_id)

register_dockable_panel(panel_type, default_visible=True)

Register dockable panel.

Parameters:

Name Type Description Default
panel_type WPFPanel

dockable panel type

 required
default_visible bool

whether panel should be visible by default

 True
Source code in pyrevitlib/pyrevit/forms/__init__.py 
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
def register_dockable_panel(panel_type, default_visible=True):
    """Register dockable panel.

    Args:
        panel_type (forms.WPFPanel): dockable panel type
        default_visible (bool, optional):
            whether panel should be visible by default
    """
    if not issubclass(panel_type, WPFPanel):
        raise PyRevitException(
            "Dockable pane must be a subclass of forms.WPFPanel"
            )

    panel_uuid = coreutils.Guid.Parse(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

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/__init__.py 
604
605
606
607
608
609
610
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/__init__.py 
613
614
615
616
617
618
619
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/__init__.py 
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
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.
    """
    dpanel_id = None
    if isinstance(panel_type_or_id, str):
        panel_id = coreutils.Guid.Parse(panel_type_or_id)
        dpanel_id = UI.DockablePaneId(panel_id)
    elif issubclass(panel_type_or_id, WPFPanel):
        panel_id = coreutils.Guid.Parse(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)
            if state:
                dockable_panel.Show()
            else:
                dockable_panel.Hide()
        else:
            raise PyRevitException(
                "Panel with id \"%s\" is not registered" % panel_type_or_id
                )

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/__init__.py 
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
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/__init__.py 
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
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)
        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/__init__.py 
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
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/__init__.py 
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
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/__init__.py 
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
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/__init__.py 
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
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/__init__.py 
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
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/__init__.py 
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
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/__init__.py 
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
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/__init__.py 
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
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/__init__.py 
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
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(
            [ParamDef(name=x.Definition.Name,
                      istype=False,
                      definition=x.Definition,
                      isreadonly=x.IsReadOnly)
             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(
                [ParamDef(name=x.Definition.Name,
                          istype=True,
                          definition=x.Definition,
                          isreadonly=x.IsReadOnly)
                 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=450,
        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)

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

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/__init__.py 
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
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):
    """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

    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

        param_defs.append(
            FamilyParamOption(family_param,
                              builtin=get_elementid_value(family_param.Id) < 0,
                              labeled=family_param.Id in label_param_ids)
            )

    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],
        },
        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/__init__.py 
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
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/__init__.py 
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
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/__init__.py 
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
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/__init__.py 
2993
2994
2995
2996
2997
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/__init__.py 
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
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/__init__.py 
3036
3037
3038
3039
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
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/__init__.py 
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
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/__init__.py 
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
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/__init__.py 
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
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/__init__.py 
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
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/__init__.py 
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
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/__init__.py 
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
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/__init__.py 
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
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/__init__.py 
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
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/__init__.py 
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
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/__init__.py 
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
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/__init__.py 
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
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/__init__.py 
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
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/__init__.py 
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
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/__init__.py 
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
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/__init__.py 
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
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)
        ```
    """
    # FIXME: window does not set default value
    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/__init__.py 
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
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/__init__.py 
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
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/__init__.py 
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
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/__init__.py 
3618
3619
3620
3621
3622
3623
3624
3625
3626
def inform_wip():
    """Show work-in-progress prompt to user and exit script.

    Examples:
        ```python
        forms.inform_wip()
        ```
    """
    alert("Work in progress.", exitscript=True)