ribbon

Base module to interact with Revit ribbon.

Attributes

mlogger = get_logger(__name__) module-attribute

PYREVIT_TAB_IDENTIFIER = 'pyrevit_tab' module-attribute

ICON_SMALL = 16 module-attribute

ICON_MEDIUM = 24 module-attribute

ICON_LARGE = 32 module-attribute

DEFAULT_DPI = 96 module-attribute

DEFAULT_TOOLTIP_IMAGE_FORMAT = '.png' module-attribute

DEFAULT_TOOLTIP_VIDEO_FORMAT = '.swf' module-attribute

Classes

PyRevitUIError

Bases: PyRevitException

Common base class for all pyRevit ui-related exceptions.

ButtonIcons(image_file)

Bases: object

pyRevit ui element icon.

Upon init, this type reads the given image file into an io stream and releases the os lock on the file.

Parameters:

Name	Type	Description	Default
image_file	str	image file path to be used as icon	required

Attributes:

Name	Type	Description
icon_file_path	str	icon image file path
filestream	FileStream	io stream containing image binary data

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def __init__(self, image_file):
    self.icon_file_path = image_file
    self.check_icon_size()
    self.filestream = IO.FileStream(image_file,
                                    IO.FileMode.Open,
                                    IO.FileAccess.Read)

Attributes

icon_file_path = image_file instance-attribute

filestream = IO.FileStream(image_file, IO.FileMode.Open, IO.FileAccess.Read) instance-attribute

small_bitmap property

Resamples image and creates bitmap for size :obj:ICON_SMALL.

Returns:

Type	Description
BitmapSource	object containing image data at given size

medium_bitmap property

Resamples image and creates bitmap for size :obj:ICON_MEDIUM.

Returns:

Type	Description
BitmapSource	object containing image data at given size

large_bitmap property

Resamples image and creates bitmap for size :obj:ICON_LARGE.

Returns:

Type	Description
BitmapSource	object containing image data at given size

Functions

recolour(image_data, size, stride, color) staticmethod

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

@staticmethod
def recolour(image_data, size, stride, color):
    # FIXME: needs doc, and argument types
    # ButtonIcons.recolour(image_data, image_size, stride, 0x8e44ad)
    step = stride / size
    for i in range(0, stride, step):
        for j in range(0, stride, step):
            idx = (i * size) + j
            # R = image_data[idx+2]
            # G = image_data[idx+1]
            # B = image_data[idx]
            # luminance = (0.299*R + 0.587*G + 0.114*B)
            image_data[idx] = color >> 0 & 0xff       # blue
            image_data[idx+1] = color >> 8 & 0xff     # green
            image_data[idx+2] = color >> 16 & 0xff    # red

check_icon_size()

Verify icon size is within acceptable range.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def check_icon_size(self):
    """Verify icon size is within acceptable range."""
    image = System.Drawing.Image.FromFile(self.icon_file_path)
    image_size = max(image.Width, image.Height)
    if image_size > 96:
        mlogger.warning('Icon file is too large. Large icons adversely '
                        'affect the load time since they need to be '
                        'processed and adjusted for screen scaling. '
                        'Keep icons at max 96x96 pixels: %s',
                        self.icon_file_path)

create_bitmap(icon_size)

Resamples image and creates bitmap for the given size.

Icons are assumed to be square.

Parameters:

Name	Type	Description	Default
icon_size	int	icon size (width or height)	required

Returns:

Type	Description
BitmapSource	object containing image data at given size

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def create_bitmap(self, icon_size):
    """Resamples image and creates bitmap for the given size.

    Icons are assumed to be square.

    Args:
        icon_size (int): icon size (width or height)

    Returns:
        (Imaging.BitmapSource): object containing image data at given size
    """
    mlogger.debug('Creating %sx%s bitmap from: %s',
                  icon_size, icon_size, self.icon_file_path)
    adjusted_icon_size = icon_size * 2
    adjusted_dpi = DEFAULT_DPI * 2
    screen_scaling = HOST_APP.proc_screen_scalefactor

    self.filestream.Seek(0, IO.SeekOrigin.Begin)
    base_image = Imaging.BitmapImage()
    base_image.BeginInit()
    base_image.StreamSource = self.filestream
    base_image.DecodePixelHeight = int(adjusted_icon_size * screen_scaling)
    base_image.EndInit()
    self.filestream.Seek(0, IO.SeekOrigin.Begin)

    image_size = base_image.PixelWidth
    image_format = base_image.Format
    image_byte_per_pixel = int(base_image.Format.BitsPerPixel / 8)
    palette = base_image.Palette

    stride = int(image_size * image_byte_per_pixel)
    array_size = stride * image_size
    image_data = System.Array.CreateInstance(System.Byte, array_size)
    base_image.CopyPixels(image_data, stride, 0)

    scaled_size = int(adjusted_icon_size * screen_scaling)
    scaled_dpi = int(adjusted_dpi * screen_scaling)
    bitmap_source = \
        Imaging.BitmapSource.Create(scaled_size, scaled_size,
                                    scaled_dpi, scaled_dpi,
                                    image_format,
                                    palette,
                                    image_data,
                                    stride)
    return bitmap_source

GenericPyRevitUIContainer()

Bases: object

Common type for all pyRevit ui containers.

Attributes:

Name	Type	Description
name	str	container name
itemdata_mode	bool	if container is wrapping UI.*ItemData

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def __init__(self):
    self.name = ''
    self._rvtapi_object = None
    self._sub_pyrvt_components = OrderedDict()
    self.itemdata_mode = False
    self._dirty = False
    self._visible = None
    self._enabled = None

Attributes

name = '' instance-attribute

itemdata_mode = False instance-attribute

visible property writable

Is container visible.

enabled property writable

Is container enabled.

Functions

process_deferred()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def process_deferred(self):
    try:
        if self._visible is not None:
            self.visible = self._visible
    except Exception as visible_err:
        raise PyRevitUIError('Error setting .visible {} | {} '
                             .format(self, visible_err))

    try:
        if self._enabled is not None:
            self.enabled = self._enabled
    except Exception as enable_err:
        raise PyRevitUIError('Error setting .enabled {} | {} '
                             .format(self, enable_err))

get_rvtapi_object()

Return underlying Revit API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_rvtapi_object(self):
    """Return underlying Revit API object for this container."""
    # FIXME: return type
    return self._rvtapi_object

set_rvtapi_object(rvtapi_obj)

Set underlying Revit API object for this container.

Parameters:

Name	Type	Description	Default
rvtapi_obj	obj	Revit API container object	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_rvtapi_object(self, rvtapi_obj):
    """Set underlying Revit API object for this container.

    Args:
        rvtapi_obj (obj): Revit API container object
    """
    # FIXME: rvtapi_obj type
    self._rvtapi_object = rvtapi_obj
    self.itemdata_mode = False
    self._dirty = True

get_adwindows_object()

Return underlying AdWindows API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_adwindows_object(self):
    """Return underlying AdWindows API object for this container."""
    # FIXME: return type
    rvtapi_obj = self._rvtapi_object
    getRibbonItemMethod = \
        rvtapi_obj.GetType().GetMethod(
            'getRibbonItem',
            BindingFlags.NonPublic | BindingFlags.Instance
            )
    if getRibbonItemMethod:
        return getRibbonItemMethod.Invoke(rvtapi_obj, None)

get_flagged_children(state=True)

Get all children with their flag equal to given state.

Flagging is a mechanism to mark certain containers. There are various reasons that container flagging might be used e.g. marking updated containers or the ones in need of an update or removal.

Parameters:

Name	Type	Description	Default
state	bool	flag state to filter children	True

Returns:

Type	Description
list[*]	list of filtered child objects

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_flagged_children(self, state=True):
    """Get all children with their flag equal to given state.

    Flagging is a mechanism to mark certain containers. There are various
    reasons that container flagging might be used e.g. marking updated
    containers or the ones in need of an update or removal.

    Args:
        state (bool): flag state to filter children

    Returns:
        (list[*]): list of filtered child objects
    """
    # FIXME: return type
    flagged_cmps = []
    for component in self:
        flagged_cmps.extend(component.get_flagged_children(state))
        if component.is_dirty() == state:
            flagged_cmps.append(component)
    return flagged_cmps

keys()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def keys(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.keys())

values()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def values(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.values())

is_native() staticmethod

Is this container generated by pyRevit or is native.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

@staticmethod
def is_native():
    """Is this container generated by pyRevit or is native."""
    return False

is_dirty()

Is dirty flag set.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def is_dirty(self):
    """Is dirty flag set."""
    if self._dirty:
        return self._dirty
    else:
        # check if there is any dirty child
        for component in self:
            if component.is_dirty():
                return True
        return False

set_dirty_flag(state=True)

Set dirty flag to given state.

See .get_flagged_children()

Parameters:

Name	Type	Description	Default
state	bool	state to set flag	True

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_dirty_flag(self, state=True):
    """Set dirty flag to given state.

    See .get_flagged_children()

    Args:
        state (bool): state to set flag
    """
    self._dirty = state

contains(pyrvt_cmp_name)

Check if container contains a component with given name.

Parameters:

Name	Type	Description	Default
pyrvt_cmp_name	str	target component name	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def contains(self, pyrvt_cmp_name):
    """Check if container contains a component with given name.

    Args:
        pyrvt_cmp_name (str): target component name
    """
    return pyrvt_cmp_name in self._sub_pyrvt_components.keys()

find_child(child_name)

Find a component with given name in children.

Parameters:

Name	Type	Description	Default
child_name	str	target component name	required

Returns:

Type	Description
Any	component object if found, otherwise None

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def find_child(self, child_name):
    """Find a component with given name in children.

    Args:
        child_name (str): target component name

    Returns:
        (Any): component object if found, otherwise None
    """
    for sub_cmp in self._sub_pyrvt_components.values():
        if child_name == sub_cmp.name:
            return sub_cmp
        elif hasattr(sub_cmp, 'ui_title') \
                and child_name == sub_cmp.ui_title:
            return sub_cmp

        component = sub_cmp.find_child(child_name)
        if component:
            return component

    return None

activate()

Activate this container in ui.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def activate(self):
    """Activate this container in ui."""
    try:
        self.enabled = True
        self.visible = True
        self._dirty = True
    except Exception:
        raise PyRevitUIError('Can not activate: {}'.format(self))

deactivate()

Deactivate this container in ui.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def deactivate(self):
    """Deactivate this container in ui."""
    try:
        self.enabled = False
        self.visible = False
        self._dirty = True
    except Exception:
        raise PyRevitUIError('Can not deactivate: {}'.format(self))

get_updated_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_updated_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children()

get_unchanged_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_unchanged_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children(state=False)

reorder_before(item_name, ritem_name)

Reorder and place item_name before ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the right	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_before(self, item_name, ritem_name):
    """Reorder and place item_name before ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the right
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx - 1)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)

reorder_beforeall(item_name)

Reorder and place item_name before all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_beforeall(self, item_name):
    """Reorder and place item_name before all others.

    Args:
        item_name (str): name of component to be moved
    """
    # FIXME: verify docs description is correct
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            apiobj.Panels.Move(litem_idx, 0)

reorder_after(item_name, ritem_name)

Reorder and place item_name after ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the left	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_after(self, item_name, ritem_name):
    """Reorder and place item_name after ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the left
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx + 1)

reorder_afterall(item_name)

Reorder and place item_name after all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_afterall(self, item_name):
    """Reorder and place item_name after all others.

    Args:
        item_name (str): name of component to be moved
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            max_idx = len(apiobj.Panels) - 1
            apiobj.Panels.Move(litem_idx, max_idx)

GenericRevitNativeUIContainer()

Bases: GenericPyRevitUIContainer

Common base type for native Revit API UI containers.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def __init__(self):
    GenericPyRevitUIContainer.__init__(self)

Attributes

name = '' instance-attribute

itemdata_mode = False instance-attribute

visible property writable

Is container visible.

enabled property writable

Is container enabled.

Functions

process_deferred()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def process_deferred(self):
    try:
        if self._visible is not None:
            self.visible = self._visible
    except Exception as visible_err:
        raise PyRevitUIError('Error setting .visible {} | {} '
                             .format(self, visible_err))

    try:
        if self._enabled is not None:
            self.enabled = self._enabled
    except Exception as enable_err:
        raise PyRevitUIError('Error setting .enabled {} | {} '
                             .format(self, enable_err))

get_rvtapi_object()

Return underlying Revit API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_rvtapi_object(self):
    """Return underlying Revit API object for this container."""
    # FIXME: return type
    return self._rvtapi_object

set_rvtapi_object(rvtapi_obj)

Set underlying Revit API object for this container.

Parameters:

Name	Type	Description	Default
rvtapi_obj	obj	Revit API container object	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_rvtapi_object(self, rvtapi_obj):
    """Set underlying Revit API object for this container.

    Args:
        rvtapi_obj (obj): Revit API container object
    """
    # FIXME: rvtapi_obj type
    self._rvtapi_object = rvtapi_obj
    self.itemdata_mode = False
    self._dirty = True

get_adwindows_object()

Return underlying AdWindows API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_adwindows_object(self):
    """Return underlying AdWindows API object for this container."""
    # FIXME: return type
    rvtapi_obj = self._rvtapi_object
    getRibbonItemMethod = \
        rvtapi_obj.GetType().GetMethod(
            'getRibbonItem',
            BindingFlags.NonPublic | BindingFlags.Instance
            )
    if getRibbonItemMethod:
        return getRibbonItemMethod.Invoke(rvtapi_obj, None)

get_flagged_children(state=True)

Get all children with their flag equal to given state.

Flagging is a mechanism to mark certain containers. There are various reasons that container flagging might be used e.g. marking updated containers or the ones in need of an update or removal.

Parameters:

Name	Type	Description	Default
state	bool	flag state to filter children	True

Returns:

Type	Description
list[*]	list of filtered child objects

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_flagged_children(self, state=True):
    """Get all children with their flag equal to given state.

    Flagging is a mechanism to mark certain containers. There are various
    reasons that container flagging might be used e.g. marking updated
    containers or the ones in need of an update or removal.

    Args:
        state (bool): flag state to filter children

    Returns:
        (list[*]): list of filtered child objects
    """
    # FIXME: return type
    flagged_cmps = []
    for component in self:
        flagged_cmps.extend(component.get_flagged_children(state))
        if component.is_dirty() == state:
            flagged_cmps.append(component)
    return flagged_cmps

keys()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def keys(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.keys())

values()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def values(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.values())

is_dirty()

Is dirty flag set.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def is_dirty(self):
    """Is dirty flag set."""
    if self._dirty:
        return self._dirty
    else:
        # check if there is any dirty child
        for component in self:
            if component.is_dirty():
                return True
        return False

set_dirty_flag(state=True)

Set dirty flag to given state.

See .get_flagged_children()

Parameters:

Name	Type	Description	Default
state	bool	state to set flag	True

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_dirty_flag(self, state=True):
    """Set dirty flag to given state.

    See .get_flagged_children()

    Args:
        state (bool): state to set flag
    """
    self._dirty = state

contains(pyrvt_cmp_name)

Check if container contains a component with given name.

Parameters:

Name	Type	Description	Default
pyrvt_cmp_name	str	target component name	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def contains(self, pyrvt_cmp_name):
    """Check if container contains a component with given name.

    Args:
        pyrvt_cmp_name (str): target component name
    """
    return pyrvt_cmp_name in self._sub_pyrvt_components.keys()

find_child(child_name)

Find a component with given name in children.

Parameters:

Name	Type	Description	Default
child_name	str	target component name	required

Returns:

Type	Description
Any	component object if found, otherwise None

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def find_child(self, child_name):
    """Find a component with given name in children.

    Args:
        child_name (str): target component name

    Returns:
        (Any): component object if found, otherwise None
    """
    for sub_cmp in self._sub_pyrvt_components.values():
        if child_name == sub_cmp.name:
            return sub_cmp
        elif hasattr(sub_cmp, 'ui_title') \
                and child_name == sub_cmp.ui_title:
            return sub_cmp

        component = sub_cmp.find_child(child_name)
        if component:
            return component

    return None

get_updated_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_updated_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children()

get_unchanged_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_unchanged_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children(state=False)

reorder_before(item_name, ritem_name)

Reorder and place item_name before ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the right	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_before(self, item_name, ritem_name):
    """Reorder and place item_name before ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the right
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx - 1)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)

reorder_beforeall(item_name)

Reorder and place item_name before all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_beforeall(self, item_name):
    """Reorder and place item_name before all others.

    Args:
        item_name (str): name of component to be moved
    """
    # FIXME: verify docs description is correct
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            apiobj.Panels.Move(litem_idx, 0)

reorder_after(item_name, ritem_name)

Reorder and place item_name after ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the left	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_after(self, item_name, ritem_name):
    """Reorder and place item_name after ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the left
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx + 1)

reorder_afterall(item_name)

Reorder and place item_name after all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_afterall(self, item_name):
    """Reorder and place item_name after all others.

    Args:
        item_name (str): name of component to be moved
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            max_idx = len(apiobj.Panels) - 1
            apiobj.Panels.Move(litem_idx, max_idx)

is_native() staticmethod

Is this container generated by pyRevit or is native.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

@staticmethod
def is_native():
    """Is this container generated by pyRevit or is native."""
    return True

activate()

Activate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def activate(self):
    """Activate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    return self.deactivate()

deactivate()

Deactivate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def deactivate(self):
    """Deactivate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    raise PyRevitUIError('Can not de/activate native item: {}'
                         .format(self))

RevitNativeRibbonButton(adwnd_ribbon_button)

Bases: GenericRevitNativeUIContainer

Revit API UI native ribbon button.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def __init__(self, adwnd_ribbon_button):
    GenericRevitNativeUIContainer.__init__(self)

    self.name = \
        safe_strtype(adwnd_ribbon_button.AutomationName)\
        .replace('\r\n', ' ')
    self._rvtapi_object = adwnd_ribbon_button

Attributes

itemdata_mode = False instance-attribute

visible property writable

Is container visible.

enabled property writable

Is container enabled.

name = safe_strtype(adwnd_ribbon_button.AutomationName).replace('\r\n', ' ') instance-attribute

Functions

process_deferred()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def process_deferred(self):
    try:
        if self._visible is not None:
            self.visible = self._visible
    except Exception as visible_err:
        raise PyRevitUIError('Error setting .visible {} | {} '
                             .format(self, visible_err))

    try:
        if self._enabled is not None:
            self.enabled = self._enabled
    except Exception as enable_err:
        raise PyRevitUIError('Error setting .enabled {} | {} '
                             .format(self, enable_err))

get_rvtapi_object()

Return underlying Revit API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_rvtapi_object(self):
    """Return underlying Revit API object for this container."""
    # FIXME: return type
    return self._rvtapi_object

set_rvtapi_object(rvtapi_obj)

Set underlying Revit API object for this container.

Parameters:

Name	Type	Description	Default
rvtapi_obj	obj	Revit API container object	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_rvtapi_object(self, rvtapi_obj):
    """Set underlying Revit API object for this container.

    Args:
        rvtapi_obj (obj): Revit API container object
    """
    # FIXME: rvtapi_obj type
    self._rvtapi_object = rvtapi_obj
    self.itemdata_mode = False
    self._dirty = True

get_adwindows_object()

Return underlying AdWindows API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_adwindows_object(self):
    """Return underlying AdWindows API object for this container."""
    # FIXME: return type
    rvtapi_obj = self._rvtapi_object
    getRibbonItemMethod = \
        rvtapi_obj.GetType().GetMethod(
            'getRibbonItem',
            BindingFlags.NonPublic | BindingFlags.Instance
            )
    if getRibbonItemMethod:
        return getRibbonItemMethod.Invoke(rvtapi_obj, None)

get_flagged_children(state=True)

Get all children with their flag equal to given state.

Flagging is a mechanism to mark certain containers. There are various reasons that container flagging might be used e.g. marking updated containers or the ones in need of an update or removal.

Parameters:

Name	Type	Description	Default
state	bool	flag state to filter children	True

Returns:

Type	Description
list[*]	list of filtered child objects

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_flagged_children(self, state=True):
    """Get all children with their flag equal to given state.

    Flagging is a mechanism to mark certain containers. There are various
    reasons that container flagging might be used e.g. marking updated
    containers or the ones in need of an update or removal.

    Args:
        state (bool): flag state to filter children

    Returns:
        (list[*]): list of filtered child objects
    """
    # FIXME: return type
    flagged_cmps = []
    for component in self:
        flagged_cmps.extend(component.get_flagged_children(state))
        if component.is_dirty() == state:
            flagged_cmps.append(component)
    return flagged_cmps

keys()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def keys(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.keys())

values()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def values(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.values())

is_native() staticmethod

Is this container generated by pyRevit or is native.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

@staticmethod
def is_native():
    """Is this container generated by pyRevit or is native."""
    return True

is_dirty()

Is dirty flag set.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def is_dirty(self):
    """Is dirty flag set."""
    if self._dirty:
        return self._dirty
    else:
        # check if there is any dirty child
        for component in self:
            if component.is_dirty():
                return True
        return False

set_dirty_flag(state=True)

Set dirty flag to given state.

See .get_flagged_children()

Parameters:

Name	Type	Description	Default
state	bool	state to set flag	True

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_dirty_flag(self, state=True):
    """Set dirty flag to given state.

    See .get_flagged_children()

    Args:
        state (bool): state to set flag
    """
    self._dirty = state

contains(pyrvt_cmp_name)

Check if container contains a component with given name.

Parameters:

Name	Type	Description	Default
pyrvt_cmp_name	str	target component name	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def contains(self, pyrvt_cmp_name):
    """Check if container contains a component with given name.

    Args:
        pyrvt_cmp_name (str): target component name
    """
    return pyrvt_cmp_name in self._sub_pyrvt_components.keys()

find_child(child_name)

Find a component with given name in children.

Parameters:

Name	Type	Description	Default
child_name	str	target component name	required

Returns:

Type	Description
Any	component object if found, otherwise None

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def find_child(self, child_name):
    """Find a component with given name in children.

    Args:
        child_name (str): target component name

    Returns:
        (Any): component object if found, otherwise None
    """
    for sub_cmp in self._sub_pyrvt_components.values():
        if child_name == sub_cmp.name:
            return sub_cmp
        elif hasattr(sub_cmp, 'ui_title') \
                and child_name == sub_cmp.ui_title:
            return sub_cmp

        component = sub_cmp.find_child(child_name)
        if component:
            return component

    return None

activate()

Activate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def activate(self):
    """Activate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    return self.deactivate()

deactivate()

Deactivate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def deactivate(self):
    """Deactivate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    raise PyRevitUIError('Can not de/activate native item: {}'
                         .format(self))

get_updated_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_updated_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children()

get_unchanged_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_unchanged_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children(state=False)

reorder_before(item_name, ritem_name)

Reorder and place item_name before ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the right	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_before(self, item_name, ritem_name):
    """Reorder and place item_name before ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the right
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx - 1)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)

reorder_beforeall(item_name)

Reorder and place item_name before all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_beforeall(self, item_name):
    """Reorder and place item_name before all others.

    Args:
        item_name (str): name of component to be moved
    """
    # FIXME: verify docs description is correct
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            apiobj.Panels.Move(litem_idx, 0)

reorder_after(item_name, ritem_name)

Reorder and place item_name after ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the left	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_after(self, item_name, ritem_name):
    """Reorder and place item_name after ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the left
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx + 1)

reorder_afterall(item_name)

Reorder and place item_name after all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_afterall(self, item_name):
    """Reorder and place item_name after all others.

    Args:
        item_name (str): name of component to be moved
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            max_idx = len(apiobj.Panels) - 1
            apiobj.Panels.Move(litem_idx, max_idx)

RevitNativeRibbonGroupItem(adwnd_ribbon_item)

Bases: GenericRevitNativeUIContainer

Revit API UI native ribbon button.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def __init__(self, adwnd_ribbon_item):
    GenericRevitNativeUIContainer.__init__(self)

    self.name = adwnd_ribbon_item.Source.Title
    self._rvtapi_object = adwnd_ribbon_item

    # finding children on this button group
    for adwnd_ribbon_button in adwnd_ribbon_item.Items:
        self._add_component(RevitNativeRibbonButton(adwnd_ribbon_button))

Attributes

itemdata_mode = False instance-attribute

visible property writable

Is container visible.

enabled property writable

Is container enabled.

name = adwnd_ribbon_item.Source.Title instance-attribute

Functions

process_deferred()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def process_deferred(self):
    try:
        if self._visible is not None:
            self.visible = self._visible
    except Exception as visible_err:
        raise PyRevitUIError('Error setting .visible {} | {} '
                             .format(self, visible_err))

    try:
        if self._enabled is not None:
            self.enabled = self._enabled
    except Exception as enable_err:
        raise PyRevitUIError('Error setting .enabled {} | {} '
                             .format(self, enable_err))

get_rvtapi_object()

Return underlying Revit API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_rvtapi_object(self):
    """Return underlying Revit API object for this container."""
    # FIXME: return type
    return self._rvtapi_object

set_rvtapi_object(rvtapi_obj)

Set underlying Revit API object for this container.

Parameters:

Name	Type	Description	Default
rvtapi_obj	obj	Revit API container object	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_rvtapi_object(self, rvtapi_obj):
    """Set underlying Revit API object for this container.

    Args:
        rvtapi_obj (obj): Revit API container object
    """
    # FIXME: rvtapi_obj type
    self._rvtapi_object = rvtapi_obj
    self.itemdata_mode = False
    self._dirty = True

get_adwindows_object()

Return underlying AdWindows API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_adwindows_object(self):
    """Return underlying AdWindows API object for this container."""
    # FIXME: return type
    rvtapi_obj = self._rvtapi_object
    getRibbonItemMethod = \
        rvtapi_obj.GetType().GetMethod(
            'getRibbonItem',
            BindingFlags.NonPublic | BindingFlags.Instance
            )
    if getRibbonItemMethod:
        return getRibbonItemMethod.Invoke(rvtapi_obj, None)

get_flagged_children(state=True)

Get all children with their flag equal to given state.

Flagging is a mechanism to mark certain containers. There are various reasons that container flagging might be used e.g. marking updated containers or the ones in need of an update or removal.

Parameters:

Name	Type	Description	Default
state	bool	flag state to filter children	True

Returns:

Type	Description
list[*]	list of filtered child objects

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_flagged_children(self, state=True):
    """Get all children with their flag equal to given state.

    Flagging is a mechanism to mark certain containers. There are various
    reasons that container flagging might be used e.g. marking updated
    containers or the ones in need of an update or removal.

    Args:
        state (bool): flag state to filter children

    Returns:
        (list[*]): list of filtered child objects
    """
    # FIXME: return type
    flagged_cmps = []
    for component in self:
        flagged_cmps.extend(component.get_flagged_children(state))
        if component.is_dirty() == state:
            flagged_cmps.append(component)
    return flagged_cmps

keys()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def keys(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.keys())

values()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def values(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.values())

is_native() staticmethod

Is this container generated by pyRevit or is native.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

@staticmethod
def is_native():
    """Is this container generated by pyRevit or is native."""
    return True

is_dirty()

Is dirty flag set.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def is_dirty(self):
    """Is dirty flag set."""
    if self._dirty:
        return self._dirty
    else:
        # check if there is any dirty child
        for component in self:
            if component.is_dirty():
                return True
        return False

set_dirty_flag(state=True)

Set dirty flag to given state.

See .get_flagged_children()

Parameters:

Name	Type	Description	Default
state	bool	state to set flag	True

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_dirty_flag(self, state=True):
    """Set dirty flag to given state.

    See .get_flagged_children()

    Args:
        state (bool): state to set flag
    """
    self._dirty = state

contains(pyrvt_cmp_name)

Check if container contains a component with given name.

Parameters:

Name	Type	Description	Default
pyrvt_cmp_name	str	target component name	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def contains(self, pyrvt_cmp_name):
    """Check if container contains a component with given name.

    Args:
        pyrvt_cmp_name (str): target component name
    """
    return pyrvt_cmp_name in self._sub_pyrvt_components.keys()

find_child(child_name)

Find a component with given name in children.

Parameters:

Name	Type	Description	Default
child_name	str	target component name	required

Returns:

Type	Description
Any	component object if found, otherwise None

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def find_child(self, child_name):
    """Find a component with given name in children.

    Args:
        child_name (str): target component name

    Returns:
        (Any): component object if found, otherwise None
    """
    for sub_cmp in self._sub_pyrvt_components.values():
        if child_name == sub_cmp.name:
            return sub_cmp
        elif hasattr(sub_cmp, 'ui_title') \
                and child_name == sub_cmp.ui_title:
            return sub_cmp

        component = sub_cmp.find_child(child_name)
        if component:
            return component

    return None

activate()

Activate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def activate(self):
    """Activate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    return self.deactivate()

deactivate()

Deactivate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def deactivate(self):
    """Deactivate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    raise PyRevitUIError('Can not de/activate native item: {}'
                         .format(self))

get_updated_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_updated_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children()

get_unchanged_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_unchanged_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children(state=False)

reorder_before(item_name, ritem_name)

Reorder and place item_name before ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the right	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_before(self, item_name, ritem_name):
    """Reorder and place item_name before ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the right
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx - 1)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)

reorder_beforeall(item_name)

Reorder and place item_name before all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_beforeall(self, item_name):
    """Reorder and place item_name before all others.

    Args:
        item_name (str): name of component to be moved
    """
    # FIXME: verify docs description is correct
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            apiobj.Panels.Move(litem_idx, 0)

reorder_after(item_name, ritem_name)

Reorder and place item_name after ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the left	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_after(self, item_name, ritem_name):
    """Reorder and place item_name after ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the left
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx + 1)

reorder_afterall(item_name)

Reorder and place item_name after all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_afterall(self, item_name):
    """Reorder and place item_name after all others.

    Args:
        item_name (str): name of component to be moved
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            max_idx = len(apiobj.Panels) - 1
            apiobj.Panels.Move(litem_idx, max_idx)

button(name)

Get button item with given name.

Parameters:

Name	Type	Description	Default
name	str	name of button item to find	required

Returns:

Type	Description
RevitNativeRibbonButton	button object if found

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def button(self, name):
    """Get button item with given name.

    Args:
        name (str): name of button item to find

    Returns:
        (RevitNativeRibbonButton): button object if found
    """
    return super(RevitNativeRibbonGroupItem, self)._get_component(name)

RevitNativeRibbonPanel(adwnd_ribbon_panel)

Bases: GenericRevitNativeUIContainer

Revit API UI native ribbon button.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def __init__(self, adwnd_ribbon_panel):
    GenericRevitNativeUIContainer.__init__(self)

    self.name = adwnd_ribbon_panel.Source.Title
    self._rvtapi_object = adwnd_ribbon_panel

    all_adwnd_ribbon_items = []
    # getting a list of existing items under this panel
    # RibbonFoldPanel items are not visible. they automatically fold
    # buttons into stack on revit ui resize since RibbonFoldPanel are
    # not visible it does not make sense to create objects for them.
    # This pre-cleaner loop, finds the RibbonFoldPanel items and
    # adds the children to the main list
    for adwnd_ribbon_item in adwnd_ribbon_panel.Source.Items:
        if isinstance(adwnd_ribbon_item, AdWindows.RibbonFoldPanel):
            try:
                for sub_rvtapi_item in adwnd_ribbon_item.Items:
                    all_adwnd_ribbon_items.append(sub_rvtapi_item)
            except Exception as append_err:
                mlogger.debug('Can not get RibbonFoldPanel children: %s '
                              '| %s', adwnd_ribbon_item, append_err)
        else:
            all_adwnd_ribbon_items.append(adwnd_ribbon_item)

    # processing the panel slideout for exising ribbon items
    for adwnd_slideout_item \
            in adwnd_ribbon_panel.Source.SlideOutPanelItemsView:
        all_adwnd_ribbon_items.append(adwnd_slideout_item)

    # processing the cleaned children list and
    # creating pyRevit native ribbon objects
    for adwnd_ribbon_item in all_adwnd_ribbon_items:
        try:
            if isinstance(adwnd_ribbon_item,
                          AdWindows.RibbonButton) \
                    or isinstance(adwnd_ribbon_item,
                                  AdWindows.RibbonToggleButton):
                self._add_component(
                    RevitNativeRibbonButton(adwnd_ribbon_item))
            elif isinstance(adwnd_ribbon_item,
                            AdWindows.RibbonSplitButton):
                self._add_component(
                    RevitNativeRibbonGroupItem(adwnd_ribbon_item))

        except Exception as append_err:
            mlogger.debug('Can not create native ribbon item: %s '
                          '| %s', adwnd_ribbon_item, append_err)

Attributes

itemdata_mode = False instance-attribute

visible property writable

Is container visible.

enabled property writable

Is container enabled.

name = adwnd_ribbon_panel.Source.Title instance-attribute

Functions

process_deferred()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def process_deferred(self):
    try:
        if self._visible is not None:
            self.visible = self._visible
    except Exception as visible_err:
        raise PyRevitUIError('Error setting .visible {} | {} '
                             .format(self, visible_err))

    try:
        if self._enabled is not None:
            self.enabled = self._enabled
    except Exception as enable_err:
        raise PyRevitUIError('Error setting .enabled {} | {} '
                             .format(self, enable_err))

get_rvtapi_object()

Return underlying Revit API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_rvtapi_object(self):
    """Return underlying Revit API object for this container."""
    # FIXME: return type
    return self._rvtapi_object

set_rvtapi_object(rvtapi_obj)

Set underlying Revit API object for this container.

Parameters:

Name	Type	Description	Default
rvtapi_obj	obj	Revit API container object	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_rvtapi_object(self, rvtapi_obj):
    """Set underlying Revit API object for this container.

    Args:
        rvtapi_obj (obj): Revit API container object
    """
    # FIXME: rvtapi_obj type
    self._rvtapi_object = rvtapi_obj
    self.itemdata_mode = False
    self._dirty = True

get_adwindows_object()

Return underlying AdWindows API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_adwindows_object(self):
    """Return underlying AdWindows API object for this container."""
    # FIXME: return type
    rvtapi_obj = self._rvtapi_object
    getRibbonItemMethod = \
        rvtapi_obj.GetType().GetMethod(
            'getRibbonItem',
            BindingFlags.NonPublic | BindingFlags.Instance
            )
    if getRibbonItemMethod:
        return getRibbonItemMethod.Invoke(rvtapi_obj, None)

get_flagged_children(state=True)

Get all children with their flag equal to given state.

Flagging is a mechanism to mark certain containers. There are various reasons that container flagging might be used e.g. marking updated containers or the ones in need of an update or removal.

Parameters:

Name	Type	Description	Default
state	bool	flag state to filter children	True

Returns:

Type	Description
list[*]	list of filtered child objects

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_flagged_children(self, state=True):
    """Get all children with their flag equal to given state.

    Flagging is a mechanism to mark certain containers. There are various
    reasons that container flagging might be used e.g. marking updated
    containers or the ones in need of an update or removal.

    Args:
        state (bool): flag state to filter children

    Returns:
        (list[*]): list of filtered child objects
    """
    # FIXME: return type
    flagged_cmps = []
    for component in self:
        flagged_cmps.extend(component.get_flagged_children(state))
        if component.is_dirty() == state:
            flagged_cmps.append(component)
    return flagged_cmps

keys()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def keys(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.keys())

values()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def values(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.values())

is_native() staticmethod

Is this container generated by pyRevit or is native.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

@staticmethod
def is_native():
    """Is this container generated by pyRevit or is native."""
    return True

is_dirty()

Is dirty flag set.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def is_dirty(self):
    """Is dirty flag set."""
    if self._dirty:
        return self._dirty
    else:
        # check if there is any dirty child
        for component in self:
            if component.is_dirty():
                return True
        return False

set_dirty_flag(state=True)

Set dirty flag to given state.

See .get_flagged_children()

Parameters:

Name	Type	Description	Default
state	bool	state to set flag	True

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_dirty_flag(self, state=True):
    """Set dirty flag to given state.

    See .get_flagged_children()

    Args:
        state (bool): state to set flag
    """
    self._dirty = state

contains(pyrvt_cmp_name)

Check if container contains a component with given name.

Parameters:

Name	Type	Description	Default
pyrvt_cmp_name	str	target component name	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def contains(self, pyrvt_cmp_name):
    """Check if container contains a component with given name.

    Args:
        pyrvt_cmp_name (str): target component name
    """
    return pyrvt_cmp_name in self._sub_pyrvt_components.keys()

find_child(child_name)

Find a component with given name in children.

Parameters:

Name	Type	Description	Default
child_name	str	target component name	required

Returns:

Type	Description
Any	component object if found, otherwise None

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def find_child(self, child_name):
    """Find a component with given name in children.

    Args:
        child_name (str): target component name

    Returns:
        (Any): component object if found, otherwise None
    """
    for sub_cmp in self._sub_pyrvt_components.values():
        if child_name == sub_cmp.name:
            return sub_cmp
        elif hasattr(sub_cmp, 'ui_title') \
                and child_name == sub_cmp.ui_title:
            return sub_cmp

        component = sub_cmp.find_child(child_name)
        if component:
            return component

    return None

activate()

Activate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def activate(self):
    """Activate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    return self.deactivate()

deactivate()

Deactivate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def deactivate(self):
    """Deactivate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    raise PyRevitUIError('Can not de/activate native item: {}'
                         .format(self))

get_updated_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_updated_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children()

get_unchanged_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_unchanged_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children(state=False)

reorder_before(item_name, ritem_name)

Reorder and place item_name before ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the right	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_before(self, item_name, ritem_name):
    """Reorder and place item_name before ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the right
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx - 1)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)

reorder_beforeall(item_name)

Reorder and place item_name before all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_beforeall(self, item_name):
    """Reorder and place item_name before all others.

    Args:
        item_name (str): name of component to be moved
    """
    # FIXME: verify docs description is correct
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            apiobj.Panels.Move(litem_idx, 0)

reorder_after(item_name, ritem_name)

Reorder and place item_name after ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the left	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_after(self, item_name, ritem_name):
    """Reorder and place item_name after ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the left
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx + 1)

reorder_afterall(item_name)

Reorder and place item_name after all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_afterall(self, item_name):
    """Reorder and place item_name after all others.

    Args:
        item_name (str): name of component to be moved
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            max_idx = len(apiobj.Panels) - 1
            apiobj.Panels.Move(litem_idx, max_idx)

ribbon_item(item_name)

Get panel item with given name.

Parameters:

Name	Type	Description	Default
item_name	str	name of panel item to find	required

Returns:

Type	Description
object	panel item if found, could be :obj:RevitNativeRibbonButton or :obj:RevitNativeRibbonGroupItem

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def ribbon_item(self, item_name):
    """Get panel item with given name.

    Args:
        item_name (str): name of panel item to find

    Returns:
        (object):
            panel item if found, could be :obj:`RevitNativeRibbonButton`
            or :obj:`RevitNativeRibbonGroupItem`
    """
    return super(RevitNativeRibbonPanel, self)._get_component(item_name)

RevitNativeRibbonTab(adwnd_ribbon_tab)

Bases: GenericRevitNativeUIContainer

Revit API UI native ribbon tab.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def __init__(self, adwnd_ribbon_tab):
    GenericRevitNativeUIContainer.__init__(self)

    self.name = adwnd_ribbon_tab.Title
    self._rvtapi_object = adwnd_ribbon_tab

    # getting a list of existing panels under this tab
    try:
        for adwnd_ribbon_panel in adwnd_ribbon_tab.Panels:
            # only listing visible panels
            if adwnd_ribbon_panel.IsVisible:
                self._add_component(
                    RevitNativeRibbonPanel(adwnd_ribbon_panel)
                )
    except Exception as append_err:
        mlogger.debug('Can not get native panels for this native tab: %s '
                      '| %s', adwnd_ribbon_tab, append_err)

Attributes

itemdata_mode = False instance-attribute

visible property writable

Is container visible.

enabled property writable

Is container enabled.

name = adwnd_ribbon_tab.Title instance-attribute

Functions

process_deferred()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def process_deferred(self):
    try:
        if self._visible is not None:
            self.visible = self._visible
    except Exception as visible_err:
        raise PyRevitUIError('Error setting .visible {} | {} '
                             .format(self, visible_err))

    try:
        if self._enabled is not None:
            self.enabled = self._enabled
    except Exception as enable_err:
        raise PyRevitUIError('Error setting .enabled {} | {} '
                             .format(self, enable_err))

get_rvtapi_object()

Return underlying Revit API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_rvtapi_object(self):
    """Return underlying Revit API object for this container."""
    # FIXME: return type
    return self._rvtapi_object

set_rvtapi_object(rvtapi_obj)

Set underlying Revit API object for this container.

Parameters:

Name	Type	Description	Default
rvtapi_obj	obj	Revit API container object	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_rvtapi_object(self, rvtapi_obj):
    """Set underlying Revit API object for this container.

    Args:
        rvtapi_obj (obj): Revit API container object
    """
    # FIXME: rvtapi_obj type
    self._rvtapi_object = rvtapi_obj
    self.itemdata_mode = False
    self._dirty = True

get_adwindows_object()

Return underlying AdWindows API object for this container.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_adwindows_object(self):
    """Return underlying AdWindows API object for this container."""
    # FIXME: return type
    rvtapi_obj = self._rvtapi_object
    getRibbonItemMethod = \
        rvtapi_obj.GetType().GetMethod(
            'getRibbonItem',
            BindingFlags.NonPublic | BindingFlags.Instance
            )
    if getRibbonItemMethod:
        return getRibbonItemMethod.Invoke(rvtapi_obj, None)

get_flagged_children(state=True)

Get all children with their flag equal to given state.

Flagging is a mechanism to mark certain containers. There are various reasons that container flagging might be used e.g. marking updated containers or the ones in need of an update or removal.

Parameters:

Name	Type	Description	Default
state	bool	flag state to filter children	True

Returns:

Type	Description
list[*]	list of filtered child objects

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_flagged_children(self, state=True):
    """Get all children with their flag equal to given state.

    Flagging is a mechanism to mark certain containers. There are various
    reasons that container flagging might be used e.g. marking updated
    containers or the ones in need of an update or removal.

    Args:
        state (bool): flag state to filter children

    Returns:
        (list[*]): list of filtered child objects
    """
    # FIXME: return type
    flagged_cmps = []
    for component in self:
        flagged_cmps.extend(component.get_flagged_children(state))
        if component.is_dirty() == state:
            flagged_cmps.append(component)
    return flagged_cmps

keys()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def keys(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.keys())

values()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def values(self):
    # FIXME: what does this do?
    list(self._sub_pyrvt_components.values())

is_native() staticmethod

Is this container generated by pyRevit or is native.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

@staticmethod
def is_native():
    """Is this container generated by pyRevit or is native."""
    return True

is_dirty()

Is dirty flag set.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def is_dirty(self):
    """Is dirty flag set."""
    if self._dirty:
        return self._dirty
    else:
        # check if there is any dirty child
        for component in self:
            if component.is_dirty():
                return True
        return False

set_dirty_flag(state=True)

Set dirty flag to given state.

See .get_flagged_children()

Parameters:

Name	Type	Description	Default
state	bool	state to set flag	True

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def set_dirty_flag(self, state=True):
    """Set dirty flag to given state.

    See .get_flagged_children()

    Args:
        state (bool): state to set flag
    """
    self._dirty = state

contains(pyrvt_cmp_name)

Check if container contains a component with given name.

Parameters:

Name	Type	Description	Default
pyrvt_cmp_name	str	target component name	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def contains(self, pyrvt_cmp_name):
    """Check if container contains a component with given name.

    Args:
        pyrvt_cmp_name (str): target component name
    """
    return pyrvt_cmp_name in self._sub_pyrvt_components.keys()

find_child(child_name)

Find a component with given name in children.

Parameters:

Name	Type	Description	Default
child_name	str	target component name	required

Returns:

Type	Description
Any	component object if found, otherwise None

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def find_child(self, child_name):
    """Find a component with given name in children.

    Args:
        child_name (str): target component name

    Returns:
        (Any): component object if found, otherwise None
    """
    for sub_cmp in self._sub_pyrvt_components.values():
        if child_name == sub_cmp.name:
            return sub_cmp
        elif hasattr(sub_cmp, 'ui_title') \
                and child_name == sub_cmp.ui_title:
            return sub_cmp

        component = sub_cmp.find_child(child_name)
        if component:
            return component

    return None

activate()

Activate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def activate(self):
    """Activate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    return self.deactivate()

deactivate()

Deactivate this container in ui.

Under current implementation, raises PyRevitUIError exception as native Revit API UI components should not be changed.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def deactivate(self):
    """Deactivate this container in ui.

    Under current implementation, raises PyRevitUIError exception as
    native Revit API UI components should not be changed.
    """
    raise PyRevitUIError('Can not de/activate native item: {}'
                         .format(self))

get_updated_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_updated_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children()

get_unchanged_items()

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_unchanged_items(self):
    # FIXME: reduntant, this is a use case and should be on uimaker side?
    return self.get_flagged_children(state=False)

reorder_before(item_name, ritem_name)

Reorder and place item_name before ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the right	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_before(self, item_name, ritem_name):
    """Reorder and place item_name before ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the right
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx - 1)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)

reorder_beforeall(item_name)

Reorder and place item_name before all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_beforeall(self, item_name):
    """Reorder and place item_name before all others.

    Args:
        item_name (str): name of component to be moved
    """
    # FIXME: verify docs description is correct
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            apiobj.Panels.Move(litem_idx, 0)

reorder_after(item_name, ritem_name)

Reorder and place item_name after ritem_name.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required
ritem_name	str	name of component that should be on the left	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_after(self, item_name, ritem_name):
    """Reorder and place item_name after ritem_name.

    Args:
        item_name (str): name of component to be moved
        ritem_name (str): name of component that should be on the left
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = ritem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
            elif item.Source.AutomationName == ritem_name:
                ritem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx and ritem_idx:
            if litem_idx < ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx)
            elif litem_idx > ritem_idx:
                apiobj.Panels.Move(litem_idx, ritem_idx + 1)

reorder_afterall(item_name)

Reorder and place item_name after all others.

Parameters:

Name	Type	Description	Default
item_name	str	name of component to be moved	required

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def reorder_afterall(self, item_name):
    """Reorder and place item_name after all others.

    Args:
        item_name (str): name of component to be moved
    """
    apiobj = self.get_rvtapi_object()
    litem_idx = None
    if hasattr(apiobj, 'Panels'):
        for item in apiobj.Panels:
            if item.Source.AutomationName == item_name:
                litem_idx = apiobj.Panels.IndexOf(item)
        if litem_idx:
            max_idx = len(apiobj.Panels) - 1
            apiobj.Panels.Move(litem_idx, max_idx)

ribbon_panel(panel_name)

Get panel with given name.

Parameters:

Name	Type	Description	Default
panel_name	str	name of panel to find	required

Returns:

Type	Description
RevitNativeRibbonPanel	panel if found

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def ribbon_panel(self, panel_name):
    """Get panel with given name.

    Args:
        panel_name (str): name of panel to find

    Returns:
        (RevitNativeRibbonPanel): panel if found
    """
    return super(RevitNativeRibbonTab, self)._get_component(panel_name)

is_pyrevit_tab() staticmethod

Is this tab generated by pyRevit.

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

@staticmethod
def is_pyrevit_tab():
    """Is this tab generated by pyRevit."""
    return False

Functions

argb_to_brush(argb_color)

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def argb_to_brush(argb_color):
    # argb_color is formatted as #AARRGGBB
    a = r = g = b = "FF"
    try:
        b = argb_color[-2:]
        g = argb_color[-4:-2]
        r = argb_color[-6:-4]
        if len(argb_color) > 7:
            a = argb_color[-8:-6]
        return Media.SolidColorBrush(Media.Color.FromArgb(
                Convert.ToInt32("0x" + a, 16),
                Convert.ToInt32("0x" + r, 16),
                Convert.ToInt32("0x" + g, 16),
                Convert.ToInt32("0x" + b, 16)
                )
            )
    except Exception as color_ex:
        mlogger.error("Bad color format %s | %s", argb_color, color_ex)

load_bitmapimage(image_file)

Load given png file.

Parameters:

Name	Type	Description	Default
image_file	str	image file path	required

Returns:

Type	Description
BitmapImage	bitmap image object

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def load_bitmapimage(image_file):
    """Load given png file.

    Args:
        image_file (str): image file path

    Returns:
        (Imaging.BitmapImage): bitmap image object
    """
    bitmap = Imaging.BitmapImage()
    bitmap.BeginInit()
    bitmap.UriSource = Uri(image_file)
    bitmap.CacheOption = Imaging.BitmapCacheOption.OnLoad
    bitmap.CreateOptions = Imaging.BitmapCreateOptions.IgnoreImageCache
    bitmap.EndInit()
    bitmap.Freeze()
    return bitmap

get_current_ui(all_native=False)

Revit UI Wrapper class for interacting with current pyRevit UI.

Returned class provides min required functionality for user interaction

Examples:

current_ui = pyrevit.session.current_ui()
this_script = pyrevit.session.get_this_command()
current_ui.update_button_icon(this_script, new_icon)

Returns:

Type	Description
_PyRevitUI	wrapper around active ribbon gui

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_current_ui(all_native=False):
    """Revit UI Wrapper class for interacting with current pyRevit UI.

    Returned class provides min required functionality for user interaction

    Examples:
        ```python
        current_ui = pyrevit.session.current_ui()
        this_script = pyrevit.session.get_this_command()
        current_ui.update_button_icon(this_script, new_icon)
        ```

    Returns:
        (_PyRevitUI): wrapper around active ribbon gui
    """
    return _PyRevitUI(all_native=all_native)

get_uibutton(command_unique_name)

Find and return ribbon ui button with given unique id.

Parameters:

Name	Type	Description	Default
command_unique_name	str	unique id of pyRevit command	required

Returns:

Type	Description
_PyRevitRibbonButton	ui button wrapper object

Source code in pyrevitlib/pyrevit/coreutils/ribbon.py

def get_uibutton(command_unique_name):
    """Find and return ribbon ui button with given unique id.

    Args:
        command_unique_name (str): unique id of pyRevit command

    Returns:
        (_PyRevitRibbonButton): ui button wrapper object
    """
    # FIXME: verify return type
    pyrvt_tabs = get_current_ui().get_pyrevit_tabs()
    for tab in pyrvt_tabs:
        button = tab.find_child(command_unique_name)
        if button:
            return button
    return None