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.

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

def pick_point(message=''):
    """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.
    """
    try:
        return HOST_APP.uidoc.Selection.PickPoint(message)
    except Exception:
        return None

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