selection

Elements selection utilities.

Attributes

mlogger = get_logger(__name__) module-attribute

Classes

ElementSelection(element_list=None)

Element selection handler.

Parameters:

Name	Type	Description	Default
element_list	list[Element]	list of selected elements	None

Source code in pyrevitlib/pyrevit/revit/selection.py

def __init__(self, element_list=None):
    if element_list is None:
        if HOST_APP.uidoc:
            self._refs = \
                [x for x in HOST_APP.uidoc.Selection.GetElementIds()]
        else:
            self._refs = []
    else:
        self._refs = ElementSelection.get_element_ids(element_list)

Attributes

is_empty property

elements property

element_ids property

first property

last property

Functions

get_element_ids(mixed_list) classmethod

Source code in pyrevitlib/pyrevit/revit/selection.py

@classmethod
def get_element_ids(cls, mixed_list):
    return ensure.ensure_element_ids(mixed_list)

set_to(element_list)

Source code in pyrevitlib/pyrevit/revit/selection.py

def set_to(self, element_list):
    self._refs = ElementSelection.get_element_ids(element_list)
    HOST_APP.uidoc.Selection.SetElementIds(
        framework.List[DB.ElementId](self._refs)
        )
    HOST_APP.uidoc.RefreshActiveView()

clear()

Source code in pyrevitlib/pyrevit/revit/selection.py

def clear(self):
    HOST_APP.uidoc.Selection.SetElementIds(
        framework.List[DB.ElementId]([DB.ElementId.InvalidElementId])
    )
    HOST_APP.uidoc.RefreshActiveView()

append(element_list)

Source code in pyrevitlib/pyrevit/revit/selection.py

def append(self, element_list):
    self._refs.extend(ElementSelection.get_element_ids(element_list))
    self.set_to(self._refs)

include(element_type)

Source code in pyrevitlib/pyrevit/revit/selection.py

def include(self, element_type):
    refs = [x for x in self._refs
            if isinstance(DOCS.doc.GetElement(x),
                          element_type)]
    return ElementSelection(refs)

exclude(element_type)

Source code in pyrevitlib/pyrevit/revit/selection.py

def exclude(self, element_type):
    refs = [x for x in self._refs
            if not isinstance(DOCS.doc.GetElement(x),
                              element_type)]
    return ElementSelection(refs)

no_views()

Source code in pyrevitlib/pyrevit/revit/selection.py

def no_views(self):
    return self.exclude(DB.View)

only_views()

Source code in pyrevitlib/pyrevit/revit/selection.py

def only_views(self):
    return self.include(DB.View)

expand_groups()

Source code in pyrevitlib/pyrevit/revit/selection.py

def expand_groups(self):
    expanded_refs = []
    for element in self.elements:
        if isinstance(element, DB.Group):
            expanded_refs.extend(element.GetMemberIds())
        else:
            expanded_refs.append(element.Id)
    self._refs = expanded_refs

PickByCategorySelectionFilter(category_id)

Bases: ISelectionFilter

Source code in pyrevitlib/pyrevit/revit/selection.py

def __init__(self, category_id):
    self.category_id = category_id

Attributes

category_id = category_id instance-attribute

Functions

AllowElement(element)

Source code in pyrevitlib/pyrevit/revit/selection.py

def AllowElement(self, element):
    if element.Category and self.category_id == element.Category.Id:
        return True
    else:
        return False

AllowReference(refer, point)

Source code in pyrevitlib/pyrevit/revit/selection.py

def AllowReference(self, refer, point):  # pylint: disable=W0613
    return False

Functions

pick_element(message='')

Asks the user to pick an element.

Parameters:

Name	Type	Description	Default
message	str	An optional message to display.	''

Returns:

Type	Description
Element	element selected by the user.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_element(message=''):
    """Asks the user to pick an element.

    Args:
        message (str): An optional message to display.

    Returns:
        (Element): element selected by the user.
    """
    return _pick_obj(UI.Selection.ObjectType.Element,
                     message)

pick_element_by_category(cat_name_or_builtin, message='')

Returns the element of the specified category picked by the user.

Parameters:

Name	Type	Description	Default
cat_name_or_builtin	str	name or built-in category of the element to pick.	required
message	str	message to display on selection. Defaults to ''.	''

Returns:

Type	Description
Element	picked element.

Raises:

Type	Description
PyRevitException	If no category matches the specified name or builtin.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_element_by_category(cat_name_or_builtin, message=''):
    """Returns the element of the specified category picked by the user.

    Args:
        cat_name_or_builtin (str): name or built-in category of the element
            to pick.
        message (str, optional): message to display on selection.
            Defaults to ''.

    Returns:
        (Element): picked element.

    Raises:
        PyRevitException: If no category matches the specified name or builtin.
    """
    category = query.get_category(cat_name_or_builtin)
    if category:
        pick_filter = PickByCategorySelectionFilter(category.Id)
        return _pick_obj(UI.Selection.ObjectType.Element,
                         message,
                         selection_filter=pick_filter)
    else:
        raise PyRevitException("Can not determine category id from: {}"
                               .format(cat_name_or_builtin))

pick_elementpoint(message='', world=False)

Returns the element point selected by the user.

Parameters:

Name	Type	Description	Default
message	str	message to display. Defaults to ''.	''
world	bool	whether to use world coordinates. Defaults to False.	False

Returns:

Type	Description
PointOnElement	The selected point.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_elementpoint(message='', world=False):
    """Returns the element point selected by the user.

    Args:
        message (str, optional): message to display. Defaults to ''.
        world (bool, optional): whether to use world coordinates. Defaults to False.

    Returns:
        (PointOnElement): The selected point.
    """
    return _pick_obj(UI.Selection.ObjectType.PointOnElement,
                     message,
                     world=world)

pick_edge(message='')

Returns the edge selected by the user.

Parameters:

Name	Type	Description	Default
message	str	message to display. Defaults to ''.	''

Returns:

Type	Description
Edge	The selected edge.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_edge(message=''):
    """Returns the edge selected by the user.

    Args:
        message (str, optional): message to display. Defaults to ''.

    Returns:
        (Edge): The selected edge.
    """
    return _pick_obj(UI.Selection.ObjectType.Edge,
                     message)

pick_face(message='')

Returns the face selected by the user.

Parameters:

Name	Type	Description	Default
message	str	message to display. Defaults to ''.	''

Returns:

Type	Description
Face	The selected face.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_face(message=''):
    """Returns the face selected by the user.

    Args:
        message (str, optional): message to display. Defaults to ''.

    Returns:
        (Face): The selected face.
    """
    return _pick_obj(UI.Selection.ObjectType.Face,
                     message)

pick_linked(message='')

Returns the linked element selected by the user.

Parameters:

Name	Type	Description	Default
message	str	message to display. Defaults to ''.	''

Returns:

Type	Description
LinkedElement	The selected linked element.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_linked(message=''):
    """Returns the linked element selected by the user.

    Args:
        message (str, optional): message to display. Defaults to ''.

    Returns:
        (LinkedElement): The selected linked element.
    """
    return _pick_obj(UI.Selection.ObjectType.LinkedElement,
                     message)

pick_elements(message='')

Asks the user to pick multiple elements.

Parameters:

Name	Type	Description	Default
message	str	An optional message to display.	''

Returns:

Type	Description
list[Element]	elements selected by the user.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_elements(message=''):
    """Asks the user to pick multiple elements.

    Args:
        message (str): An optional message to display.

    Returns:
        (list[Element]): elements selected by the user.
    """
    return _pick_obj(UI.Selection.ObjectType.Element,
                     message,
                     multiple=True)

pick_elements_by_category(cat_name_or_builtin, message='')

Returns the elements of the specified category picked by the user.

Parameters:

Name	Type	Description	Default
cat_name_or_builtin	str	name or built-in category of the elements to pick.	required
message	str	message to display on selection. Defaults to ''.	''

Returns:

Type	Description
list[Element]	picked elements.

Raises:

Type	Description
PyRevitException	If no category matches the specified name or builtin.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_elements_by_category(cat_name_or_builtin, message=''):
    """Returns the elements of the specified category picked by the user.

    Args:
        cat_name_or_builtin (str): name or built-in category of the elements
            to pick.
        message (str, optional): message to display on selection.
            Defaults to ''.

    Returns:
        (list[Element]): picked elements.

    Raises:
        PyRevitException: If no category matches the specified name or builtin.
    """
    category = query.get_category(cat_name_or_builtin)
    if category:
        pick_filter = PickByCategorySelectionFilter(category.Id)
        return _pick_obj(UI.Selection.ObjectType.Element,
                         message,
                         multiple=True,
                         selection_filter=pick_filter)
    else:
        raise PyRevitException("Can not determine category id from: {}"
                               .format(cat_name_or_builtin))

get_picked_elements(message='')

Allows the user to pick multple elements, one at a time.

It keeps asking the user to pick an element until no elements are selected.

Parameters:

Name	Type	Description	Default
message	str	The message to display. Defaults to ''.	''

Yields:

Type	Description
Element	selected element

Source code in pyrevitlib/pyrevit/revit/selection.py

def get_picked_elements(message=''):
    """Allows the user to pick multple elements, one at a time.

    It keeps asking the user to pick an element until no elements are selected.

    Args:
        message (str, optional): The message to display. Defaults to ''.

    Yields:
        (DB.Element): selected element
    """
    picked_element = True
    while picked_element:
        picked_element = pick_element(message=message)
        if not picked_element:
            break
        yield picked_element

get_picked_elements_by_category(cat_name_or_builtin, message='')

Pick elements by category.

Keeps asking the user to pick an element until no elements are selected.

Parameters:

Name	Type	Description	Default
cat_name_or_builtin	str	category name or built-in category.	required
message	str	message to display while picking elements.	''

Yields:

Type	Description
Element	The picked elements from the specified category.

Source code in pyrevitlib/pyrevit/revit/selection.py

def get_picked_elements_by_category(cat_name_or_builtin, message=''):
    """Pick elements by category.

    Keeps asking the user to pick an element until no elements are selected.

    Args:
        cat_name_or_builtin (str): category name or built-in category.
        message (str, optional): message to display while picking elements.

    Yields:
        (DB.Element): The picked elements from the specified category.
    """
    picked_element = True
    while picked_element:
        picked_element = pick_element_by_category(cat_name_or_builtin,
                                                  message=message)
        if not picked_element:
            break
        yield picked_element

pick_elementpoints(message='', world=False)

Selects element points.

Parameters:

Name	Type	Description	Default
message	str	The message to display when selecting element points.	''
world	bool	Select points in world coordinates. Defaults to False.	False

Returns:

Type	Description
list[PointOnElement]	selected element points.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_elementpoints(message='', world=False):
    """Selects element points.

    Args:
        message (str): The message to display when selecting element points.
        world (bool, optional): Select points in world coordinates. Defaults to False.

    Returns:
        (list[PointOnElement]): selected element points.
    """
    return _pick_obj(UI.Selection.ObjectType.PointOnElement,
                     message,
                     multiple=True, world=world)

pick_edges(message='')

Selects edges.

Parameters:

Name	Type	Description	Default
message	str	The message to display when selecting edges.	''

Returns:

Type	Description
list[Edge]	selected edges.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_edges(message=''):
    """Selects edges.

    Args:
        message (str): The message to display when selecting edges.

    Returns:
        (list[Edge]): selected edges.
    """
    return _pick_obj(UI.Selection.ObjectType.Edge,
                     message,
                     multiple=True)

pick_faces(message='')

Selects faces.

Parameters:

Name	Type	Description	Default
message	str	The message to display when selecting the faces.	''

Returns:

Type	Description
list[Face]	selected faces.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_faces(message=''):
    """Selects faces.

    Args:
        message (str): The message to display when selecting the faces.

    Returns:
        (list[Face]): selected faces.
    """
    return _pick_obj(UI.Selection.ObjectType.Face,
                     message,
                     multiple=True)

pick_linkeds(message='')

Selects linked elements.

Parameters:

Name	Type	Description	Default
message	str	The message to display when selecting linked elements.	''

Returns:

Type	Description
list[LinkedElement]	selected linked elements.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_linkeds(message=''):
    """Selects linked elements.

    Args:
        message (str): The message to display when selecting linked elements.

    Returns:
        (list[LinkedElement]): selected linked elements.
    """
    return _pick_obj(UI.Selection.ObjectType.LinkedElement,
                     message,
                     multiple=True)

pick_point(message='')

Pick a point from the user interface.

Parameters:

Name	Type	Description	Default
message	str	A message to display when prompting for the point.	''

Returns:

Type	Description
tuple or None	A tuple representing the picked point as (x, y, z) coordinates, or None if no point was picked or an error occurred.

Side Effects

If the active view does not have a SketchPlane assigned, this function will automatically create a temporary work plane (aligned with the active view) and assign it to the view before prompting for the point. The work plane is removed after picking to avoid modifying the document.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_point(message=''):
    # type: (str) -> DB.XYZ | None
    """Pick a point from the user interface.

    Args:
        message (str): A message to display when prompting for the point.

    Returns:
        (tuple or None): A tuple representing the picked point as (x, y, z)
            coordinates, or None if no point was picked or an error occurred.

    Side Effects:
        If the active view does not have a ``SketchPlane`` assigned, this
        function will automatically create a temporary work plane (aligned with the
        active view) and assign it to the view before prompting for the point.
        The work plane is removed after picking to avoid modifying the document.
    """
    doc = HOST_APP.doc
    active_view = doc.ActiveView
    result = None

    try:
        if active_view.SketchPlane is None:
            tg = DB.TransactionGroup(doc, "Assigning a workplane to the current view")
            tg.Start()

            with DB.Transaction(doc, "Create temporary workplane") as t:
                t.Start()
                try:
                    sketch_plane = DB.SketchPlane.Create(
                        doc,
                        DB.Plane.CreateByNormalAndOrigin(
                            active_view.ViewDirection,
                            active_view.Origin
                        )
                    )
                    active_view.SketchPlane = sketch_plane
                    t.Commit()
                except Exception as ex:
                    mlogger.error("Failed to create temporary sketch plane: %s", ex)
                    t.RollBack()
                    tg.RollBack()
                    return None

            result = HOST_APP.uidoc.Selection.PickPoint(message)

            tg.RollBack()
        else:
            result = HOST_APP.uidoc.Selection.PickPoint(message)

    except RevitExceptions.OperationCanceledException:
        mlogger.debug("Operation canceled by user")
        return None
    except Exception as ex:
        mlogger.error("An error occurred during point picking: %s", ex)
        return None

    return result

pick_rectangle(message='', pick_filter=None)

Picks elements from the user interface by specifying a rectangular area.

Parameters:

Name	Type	Description	Default
message	str	A custom message to display when prompting the user to pick elements. Default is an empty string.	''
pick_filter	object	An object specifying the filter to apply when picking elements. Default is None.	None

Returns:

Type	Description
list[ElementId]	The selected elements.

Source code in pyrevitlib/pyrevit/revit/selection.py

def pick_rectangle(message='', pick_filter=None):
    """Picks elements from the user interface by specifying a rectangular area.

    Args:
        message (str, optional): A custom message to display when prompting
            the user to pick elements. Default is an empty string.
        pick_filter (object, optional): An object specifying the filter to apply
            when picking elements. Default is None.

    Returns:
        (list[DB.ElementId]): The selected elements.
    """
    if pick_filter:
        return HOST_APP.uidoc.Selection.PickElementsByRectangle(pick_filter,
                                                                message)
    else:
        return HOST_APP.uidoc.Selection.PickElementsByRectangle(message)

get_selection_category_set()

Returns a CategorySet with the categories of the selected elements.

Returns:

Type	Description
CategorySet	categories of the selected elements.

Source code in pyrevitlib/pyrevit/revit/selection.py

def get_selection_category_set():
    """Returns a CategorySet with the categories of the selected elements.

    Returns:
        (CategorySet): categories of the selected elements.
    """
    selection = ElementSelection()
    cset = DB.CategorySet()
    for element in selection:
        cset.Insert(element.Category)
    return cset

get_selection()

Returns the current selected items.

Returns:

Type	Description
ElementSelection	the current selected items

Source code in pyrevitlib/pyrevit/revit/selection.py

def get_selection():
    """Returns the current selected items.

    Returns:
        (ElementSelection): the current selected items
    """
    return ElementSelection()