Welcome to PyQtRibbon’s documentation!

Ribbon Bar for PyQt or PySide applications.

GitHub Repository: github.com/haiiliin/pyqtribbon.
PyPI: pypi.org/project/pyqtribbon.
Documentation: pyqribbon.readthedocs.io/en/stable.
Read the Docs: readthedocs.org/projects/pyqtribbon.

Getting Started

Installation

PyQtRibbon is distribued to PyPI, you can use pip to install it:

pip install pyqtribbon

You can also install the package from source:

pip install git+https://github.com/haiiliin/pyqtribbon.git@main

The Ribbon Bar

Introduction

The ribbon is first introduced by Microsoft in the 2000’s. It is a toolbar with a tabbed interface. According to Microsoft:

Note

A ribbon is a user interface (UI) element that organizes commands into logical groups. These groups appear on separate tabs in a strip across the top of the window. The ribbon replaces the menu bar and toolbars. A ribbon can significantly improve application usability. For more information, see Ribbons. The following illustration shows a ribbon. A ribbon can significantly improve application usability. For more information, see Ribbons. The following illustration shows a ribbon.

Definitions of Ribbon Elements

Application button: The button that appears on the upper-left corner of a ribbon. The Application button replaces the File menu and is visible even when the ribbon is minimized. When the button is clicked, a menu that has a list of commands is displayed.
Quick Access toolbar: A small, customizable toolbar that displays frequently used commands.
Category: The logical grouping that represents the contents of a ribbon tab.
Category Default button: The button that appears on the ribbon when the ribbon is minimized. When the button is clicked, the category reappears as a menu.
Panel: An area of the ribbon bar that displays a group of related controls. Every ribbon category contains one or more ribbon panels.
Ribbon elements: Controls in the panels, for example, buttons and combo boxes. To see the various controls that can be hosted on a ribbon, see RibbonGadgets Sample: Ribbon Gadgets Application.

Ribbon Elements in PyQtRibbon

User Manual

The RibbonScreenShotWindow Class

The RibbonScreenShotWindow class is just for taking a screenshot of the window, the window will be closed 0.1s after it is shown. It is just used for documenting the window.

class pyqtribbon.screenshotwindow.RibbonScreenShotWindow(fileName: str = 'shot.jpg', *args, **kwargs)[source]

This class is just for taking a screenshot of the window, the window will be closed 0.1s after it is shown.

Initialize the class.

Parameters:: fileName – The file name for the screenshot.

setScreenShotFileName(fileName: str)[source]

Set the file name for the screenshot.

Parameters:: fileName – The file name for the screenshot.

takeScreenShot()[source]: Take a screenshot of the window.

Instantiate a Ribbon Bar

RibbonBar is inherited from QMenuBar, you can use the setMenuBar method of QMainWindow to set the ribbon bar as the main menu bar.

from pyqtribbon import RibbonBar

window = QtWidgets.QMainWindow()
ribbon = RibbonBar()
window.setMenuBar(ribbon)

Example

For example, using the following code,

import sys

from qtpy import QtGui, QtWidgets

from pyqtribbon import RibbonBar
from pyqtribbon.screenshotwindow import RibbonScreenShotWindow

if __name__ == "__main__":
    app = QtWidgets.QApplication(sys.argv)
    app.setFont(QtGui.QFont("Times New Roman", 8))
    window = RibbonScreenShotWindow("ribbonbar.png")

    # Ribbon bar
    ribbonbar = RibbonBar()
    window.setMenuBar(ribbonbar)

    # Show the window
    window.resize(1000, 250)
    window.show()

    sys.exit(app.exec_())

You can get a window like this:

Customize Ribbon Bar

General Setups

`RibbonBar.setRibbonStyle`(style)	Set the style of the ribbon.
`RibbonBar.ribbonHeight`()	Get the total height of the ribbon.
`RibbonBar.setRibbonHeight`(height)	Set the total height of the ribbon.
`RibbonBar.showRibbon`()	Show the ribbon.
`RibbonBar.hideRibbon`()	Hide the ribbon.
`RibbonBar.ribbonVisible`()	Get the visibility of the ribbon.
`RibbonBar.setRibbonVisible`(visible)	Set the visibility of the ribbon.

Setup Application Button

`RibbonBar.applicationOptionButton`()	Return the application button.
`RibbonBar.setApplicationIcon`(icon)	Set the application icon.
`RibbonBar.addFileMenu`()	Add a file menu to the ribbon.

Setup Title

`RibbonBar.title`()	Return the title of the ribbon.
`RibbonBar.setTitle`(title)	Set the title of the ribbon.
`RibbonBar.addTitleWidget`(widget)	Add a widget to the title widget.
`RibbonBar.insertTitleWidget`(index, widget)	Insert a widget to the title widget.
`RibbonBar.removeTitleWidget`(widget)	Remove a widget from the title widget.

Setup Category Tab Bar

RibbonBar.tabBar()

Return the tab bar of the ribbon.

Setup Quick Access Bar

`RibbonBar.quickAccessToolBar`()	Return the quick access toolbar of the ribbon.
`RibbonBar.addQuickAccessButton`(button)	Add a button to the quick access bar.
`RibbonBar.setQuickAccessButtonHeight`([height])	Set the height of the quick access buttons.

Setup Right Tool Bar

`RibbonBar.rightToolBar`()	Return the right toolbar of the ribbon.
`RibbonBar.addRightToolButton`(button)	Add a widget to the right button bar.
`RibbonBar.setRightToolBarHeight`([height])	Set the height of the right buttons.
`RibbonBar.setHelpButtonIcon`(icon)	Set the icon of the help button.
`RibbonBar.removeHelpButton`()	Remove the help button from the ribbon.
`RibbonBar.helpButtonClicked`(bool)	Signal, the help button was clicked.
`RibbonBar.collapseRibbonButton`()	Return the collapse ribbon button.
`RibbonBar.setCollapseButtonIcon`(icon)	Set the icon of the min button.
`RibbonBar.removeCollapseButton`()	Remove the min button from the ribbon.

Example

For example, using the following code,

import sys

from qtpy import QtGui
from qtpy.QtWidgets import QApplication, QToolButton

from pyqtribbon import RibbonBar
from pyqtribbon.screenshotwindow import RibbonScreenShotWindow

if __name__ == "__main__":
    app = QApplication(sys.argv)
    app.setFont(QtGui.QFont("Times New Roman", 8))
    window = RibbonScreenShotWindow("ribbonbar-customize.png")

    # Ribbon bar
    ribbonbar = RibbonBar()
    window.setMenuBar(ribbonbar)

    # Title of the ribbon
    ribbonbar.setTitle("This is my custom title")

    # Quick Access Bar
    qbutton = QToolButton()
    qbutton.setText("Quick Button")
    ribbonbar.addQuickAccessButton(qbutton)

    # Right toolbar
    rbutton = QToolButton()
    rbutton.setText("Right Button")
    ribbonbar.addRightToolButton(rbutton)

    # Show the window
    window.resize(1000, 250)
    window.show()

    sys.exit(app.exec_())

You can get a window like this:

Manage Categories

`RibbonBar.categories`()	Return a list of categories of the ribbon.
`RibbonBar.addCategory`(title[, style, color])	Add a new category to the ribbon.
`RibbonBar.addCategoriesBy`(data)	Add categories from a dict.
`RibbonBar.addNormalCategory`(title)	Add a new category to the ribbon.
`RibbonBar.addContextCategory`(title[, color])	Add a new context category to the ribbon.
`RibbonBar.addContextCategories`(name, titles)	Add a group of context categories with the same tab color to the ribbon.
`RibbonBar.showContextCategory`(category)	Show the given category or categories, if it is not a context category, nothing happens.
`RibbonBar.hideContextCategory`(category)	Hide the given category or categories, if it is not a context category, nothing happens.
`RibbonBar.removeCategory`(category)	Remove a category from the ribbon.
`RibbonBar.setCurrentCategory`(category)	Set the current category.
`RibbonBar.currentCategory`()	Return the current category.
`RibbonBar.showCategoryByIndex`(index)	Show category by tab index

Customize Categories

Setup Styles

`RibbonCategory.categoryStyle`()	Return the button style of the category.
`RibbonCategory.setCategoryStyle`(style)	Set the button style of the category.

Manage Panels

`RibbonCategory.addPanel`(title[, ...])	Add a new panel to the category.
`RibbonCategory.addPanelsBy`(data)	Add panels from a dictionary.
`RibbonCategory.removePanel`(title)	Remove a panel from the category.
`RibbonCategory.takePanel`(title)	Remove and return a panel from the category.
`RibbonCategory.panel`(title)	Return a panel from the category.
`RibbonCategory.panels`()	Return all panels in the category.

Example

For example, using the following code,

import sys

from qtpy import QtGui
from qtpy.QtGui import QIcon
from qtpy.QtWidgets import QApplication

from pyqtribbon import RibbonBar, RibbonCategoryStyle
from pyqtribbon.screenshotwindow import RibbonScreenShotWindow

if __name__ == "__main__":
    app = QApplication(sys.argv)
    app.setFont(QtGui.QFont("Times New Roman", 8))
    window = RibbonScreenShotWindow("category.png")

    # Ribbon bar
    ribbonbar = RibbonBar()
    window.setMenuBar(ribbonbar)

    # Categories
    category1 = ribbonbar.addCategory("Category 1")
    panel1 = category1.addPanel("Panel 1")
    panel1.addLargeButton("Large Button 1", QIcon("python.png"))

    category2 = ribbonbar.addContextCategory("Category 2")
    panel12 = category2.addPanel("Panel 2")
    panel12.addLargeButton("Large Button 2", QIcon("python.png"))

    categories = ribbonbar.addCategoriesBy(
        {
            "Category 6": {
                "style": RibbonCategoryStyle.Normal,
                "panels": {
                    "Panel 1": {
                        "showPanelOptionButton": True,
                        "widgets": {
                            "Button 1": {
                                "type": "Button",
                                "arguments": {
                                    "icon": QIcon("python.png"),
                                    "text": "Button",
                                    "tooltip": "This is a tooltip",
                                },
                            },
                        },
                    },
                },
            }
        }
    )
    ribbonbar.setCurrentCategory(categories["Category 6"])

    # Show the window
    window.resize(1000, 250)
    window.show()

    sys.exit(app.exec_())

You can get a window like this:

Customize Panels

Setup Title Label

`RibbonPanel.title`()	Get the title of the panel.
`RibbonPanel.setTitle`(title)	Set the title of the panel.

Setup Panel Option Button

`RibbonPanel.panelOptionButton`()	Return the panel option button.
`RibbonPanel.setPanelOptionToolTip`(text)	Set the tooltip of the panel option button.
`RibbonPanel.panelOptionClicked`(bool)	int = ..., arguments: Sequence = ...) -> PYQT_SIGNAL

Add Widgets to Panels

`RibbonPanel.addWidget`(widget, *[, rowSpan, ...])	Add a widget to the panel.
`RibbonPanel.addWidgetsBy`(data)	Add widgets to the panel.
`RibbonPanel.removeWidget`(widget)	Remove a widget from the panel.
`RibbonPanel.widget`(index)	Get the widget at the given index.
`RibbonPanel.widgets`()	Get all the widgets in the panel.
`RibbonPanel.addSmallWidget`(widget, *[, ...])
`RibbonPanel.addMediumWidget`(widget, *[, ...])
`RibbonPanel.addLargeWidget`(widget, *[, ...])
`RibbonPanel.addButton`([text, icon, ...])	Add a button to the panel.
`RibbonPanel.addSmallButton`([text, icon, ...])
`RibbonPanel.addMediumButton`([text, icon, ...])
`RibbonPanel.addLargeButton`([text, icon, ...])
`RibbonPanel.addToggleButton`([text, icon, ...])
`RibbonPanel.addSmallToggleButton`([text, ...])
`RibbonPanel.addMediumToggleButton`([text, ...])
`RibbonPanel.addLargeToggleButton`([text, ...])
`RibbonPanel.addComboBox`(args, *kwargs)
`RibbonPanel.addFontComboBox`(args, *kwargs)
`RibbonPanel.addLineEdit`(args, *kwargs)
`RibbonPanel.addTextEdit`(args, *kwargs)
`RibbonPanel.addPlainTextEdit`(args, *kwargs)
`RibbonPanel.addLabel`(args, *kwargs)
`RibbonPanel.addProgressBar`(args, *kwargs)
`RibbonPanel.addSlider`(args, *kwargs)
`RibbonPanel.addSpinBox`(args, *kwargs)
`RibbonPanel.addDoubleSpinBox`(args, *kwargs)
`RibbonPanel.addDateEdit`(args, *kwargs)
`RibbonPanel.addTimeEdit`(args, *kwargs)
`RibbonPanel.addDateTimeEdit`(args, *kwargs)
`RibbonPanel.addTableWidget`(args, *kwargs)
`RibbonPanel.addTreeWidget`(args, *kwargs)
`RibbonPanel.addListWidget`(args, *kwargs)
`RibbonPanel.addCalendarWidget`(args, *kwargs)
`RibbonPanel.addSeparator`([orientation, width])	Add a separator to the panel.
`RibbonPanel.addHorizontalSeparator`(*[, ...])
`RibbonPanel.addVerticalSeparator`(*[, ...])
`RibbonPanel.addGallery`([minimumWidth, ...])	Add a gallery to the panel.

Example

For example, using the following code,

import sys

from qtpy import QtGui
from qtpy.QtCore import Qt
from qtpy.QtGui import QIcon
from qtpy.QtWidgets import QApplication, QLabel, QLineEdit, QMenu, QToolButton

from pyqtribbon import RibbonBar
from pyqtribbon.screenshotwindow import RibbonScreenShotWindow

if __name__ == "__main__":
    app = QApplication(sys.argv)
    app.setFont(QtGui.QFont("Times New Roman", 8))
    window = RibbonScreenShotWindow("panel.png")

    # Ribbon bar
    ribbonbar = RibbonBar()
    window.setMenuBar(ribbonbar)

    category1 = ribbonbar.addCategory("Category 1")
    panel = category1.addPanel("Panel 1", showPanelOptionButton=False)
    panel.addSmallButton("Button 1", icon=QIcon("python.png"))
    panel.addSmallButton("Button 2", icon=QIcon("python.png"))
    panel.addSmallButton("Button 3", icon=QIcon("python.png"))
    panel.addMediumToggleButton("Show/Hide Category 2", icon=QIcon("python.png"))
    panel.addVerticalSeparator()
    panel.addMediumToggleButton("Show/Hide Category 3", icon=QIcon("python.png"))
    panel.addMediumToggleButton("Show/Hide Category 4/5", icon=QIcon("python.png"), colSpan=2, alignment=Qt.AlignLeft)
    panel.addLargeButton("Button 4", icon=QIcon("python.png"))
    panel.addVerticalSeparator()
    panel.addMediumButton("Button 5", icon=QIcon("python.png"))
    panel.addMediumButton("Button 6", icon=QIcon("python.png"))

    button = panel.addLargeButton("Button 7", icon=QIcon("python.png"))
    menu = QMenu()
    menu.addAction(QIcon("python.png"), "Action 1")
    menu.addAction(QIcon("python.png"), "Action 2")
    menu.addAction(QIcon("python.png"), "Action 3")
    button.setMenu(menu)
    button.setPopupMode(QToolButton.InstantPopup)
    panel.addWidget(button, rowSpan=6)

    gallery = panel.addGallery(minimumWidth=500, popupHideOnClick=True)
    for i in range(100):
        gallery.addToggleButton(f"item {i+1}", QIcon("python.png"))
    popupMenu = gallery.popupMenu()
    submenu = popupMenu.addMenu(QIcon("python.png"), "Submenu")
    submenu.addAction(QIcon("python.png"), "Action 4")
    popupMenu.addAction(QIcon("python.png"), "Action 1")
    popupMenu.addAction(QIcon("python.png"), "Action 2")
    popupMenu.addSeparator()
    popupMenu.addWidget(QLabel("This is a custom widget"))
    formLayout = popupMenu.addFormLayoutWidget()
    formLayout.addRow(QLabel("Row 1"), QLineEdit())

    # Show the window
    window.resize(1300, 250)
    window.show()

    sys.exit(app.exec_())

You can get a window like this:

A Complete Example

The following code snippet is a complete example.

import sys

from PyQt5.QtCore import Qt
from PyQt5.QtGui import QFont, QIcon
from PyQt5.QtWidgets import QApplication, QLabel, QVBoxLayout, QWidget

from pyqtribbon import RibbonBar
from pyqtribbon.screenshotwindow import RibbonScreenShotWindow
from pyqtribbon.utils import DataFile

if __name__ == "__main__":
    app = QApplication(sys.argv)
    app.setFont(QFont("Times New Roman", 8))

    # Central widget
    window = RibbonScreenShotWindow("tutorial-ribbonbar.png")
    window.setWindowIcon(QIcon(DataFile("icons/python.png")))
    centralWidget = QWidget()
    window.setCentralWidget(centralWidget)
    layout = QVBoxLayout(centralWidget)

    # Ribbon bar
    ribbonbar = RibbonBar()
    window.setMenuBar(ribbonbar)
    category = ribbonbar.addCategory("Category 1")
    panel = category.addPanel("Panel 1")
    panel.addLargeButton("A Large Button", QIcon(DataFile("icons/python.png")))
    panel.addMediumButton("A Medium Button", QIcon(DataFile("icons/python.png")))
    panel.addMediumButton("A Medium Button", QIcon(DataFile("icons/python.png")))
    panel.addSmallButton("A Small Button", QIcon(DataFile("icons/python.png")))
    panel.addSmallButton("A Small Button", QIcon(DataFile("icons/python.png")))
    panel.addSmallButton("A Small Button", QIcon(DataFile("icons/python.png")))

    # Display a label in the main window
    label = QLabel("Ribbon Test Window")
    label.setFont(QFont("Arial", 20))
    label.setAlignment(Qt.AlignCenter)

    # Add the ribbon bar and label to the layout
    layout.addWidget(label, 1)

    # Show the window
    window.resize(1800, 350)  # type: ignore
    window.show()
    sys.exit(app.exec_())

You can get a window like this:

API References

pyqtribbon package

Submodules

pyqtribbon.category module

class pyqtribbon.category.RibbonCategory(title: str = '', style: RibbonCategoryStyle = RibbonCategoryStyle.Normal, color: QColor = None, parent=None)[source]

class pyqtribbon.category.RibbonCategory(parent=None)

Bases: RibbonCategoryLayoutWidget

The RibbonCategory is the logical grouping that represents the contents of a ribbon tab.

Create a new category.

Parameters:

title – The title of the category.
style – The button style of the category.
color – The color of the context category.
parent – The parent widget.

addPanel(title: str, showPanelOptionButton=True) → RibbonPanel[source]

Add a new panel to the category.

Parameters:

title – The title of the panel.
showPanelOptionButton – Whether to show the panel option button.

Returns:

The newly created panel.

addPanelsBy(data: Dict[str, Dict]) → Dict[str, RibbonPanel][source]

Add panels from a dictionary.

Parameters:

data –

The dictionary. The keys are the titles of the panels. The value is a dictionary of arguments. the argument showPanelOptionButton is a boolean to decide whether to show the panel option button, the rest arguments are passed to the RibbonPanel.addWidgetsBy() method. The dict is of the form:

{
    "panel-title": {
        "showPanelOptionButton": True,
        "widgets": {
            "widget-name": {
                "type": "Button",
                "arguments": {
                    "key1": "value1",
                    "key2": "value2"
                }
            },
        }
    },
}

Returns:

A dictionary of the newly created panels.

categoryStyle() → RibbonCategoryStyle[source]

Return the button style of the category.

Returns:: The button style.

panel(title: str) → RibbonPanel[source]

Return a panel from the category.

Parameters:: title – The title of the panel.
Returns:: The panel.

panels() → Dict[str, RibbonPanel][source]

Return all panels in the category.

Returns:: The panels.

removePanel(title: str)[source]

Remove a panel from the category.

Parameters:: title – The title of the panel.

setCategoryStyle(style: RibbonCategoryStyle)[source]

Set the button style of the category.

Parameters:: style – The button style.

setMaximumRows(rows: int)[source]

Set the maximum number of rows.

Parameters:: rows – The maximum number of rows.

takePanel(title: str) → RibbonPanel[source]

Remove and return a panel from the category.

Parameters:: title – The title of the panel.
Returns:: The removed panel.

title() → str[source]: Return the title of the category.

class pyqtribbon.category.RibbonCategoryLayoutButton[source]

Bases: QToolButton

Previous/Next buttons in the category when the size is not enough for the widgets.

class pyqtribbon.category.RibbonCategoryLayoutWidget(parent=None)[source]

Bases: QFrame

The category layout widget’s category scroll area to arrange the widgets in the category.

Create a new category layout widget.

Parameters:: parent – The parent widget.

addWidget(widget: QWidget)[source]

Add a widget to the category layout.

Parameters:: widget – The widget to add.

autoSetScrollButtonsVisible()[source]: Set the visibility of the scroll buttons.

displayOptionsButtonClicked[source]

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:: pyqtSignal(*types, name
Type:: str = …, revision

paintEvent(a0: QPaintEvent) → None[source]: Override the paint event to draw the background.

removeWidget(widget: QWidget)[source]

Remove a widget from the category layout.

Parameters:: widget – The widget to remove.

resizeEvent(a0: QResizeEvent) → None[source]: Override the resize event to resize the scroll area.

scrollNext()[source]: Scroll the category to the next widget.

scrollPrevious()[source]: Scroll the category to the previous widget.

takeWidget(widget: QWidget) → QWidget[source]

Remove and return a widget from the category layout.

Parameters:: widget – The widget to remove.
Returns:: The widget that was removed.

class pyqtribbon.category.RibbonCategoryScrollArea[source]

Bases: QScrollArea

Scroll area for the gallery

class pyqtribbon.category.RibbonCategoryScrollAreaContents[source]

Bases: QFrame

Scroll area contents for the gallery

class pyqtribbon.category.RibbonContextCategories(name: str, color: QColor, categories: Dict[str, RibbonContextCategory], ribbon)[source]

Bases: Dict[str, RibbonContextCategory]

A list of context categories.

categoriesVisible() → bool[source]: Return whether the categories are shown.

color() → QColor[source]: Return the color of the context categories.

hideContextCategories()[source]: Hide the categories

name() → str[source]: Return the name of the context categories.

setCategoriesVisible(visible: bool)[source]: Set the state of the categories.

setColor(color: QColor)[source]: Set the color of the context categories.

setName(name: str)[source]: Set the name of the context categories.

showContextCategories()[source]: Show the categories

class pyqtribbon.category.RibbonContextCategory(title: str, color: QColor, parent: QWidget)[source]

Bases: RibbonCategory

A context category.

Create a new context category.

Parameters:

title – The title of the category.
color – The color of the context category.
parent – The parent widget.

categoryVisible() → bool[source]

Return whether the category is shown.

Returns:: Whether the category is shown.

color() → QColor[source]

Return the color of the context category.

Returns:: The color of the context category.

hideContextCategory()[source]: Hide the given category, if it is not a context category, nothing happens.

setCategoryStyle(style: RibbonCategoryStyle)[source]

Set the button style of the category.

Parameters:: style – The button style.

setCategoryVisible(visible: bool)[source]

Set the state of the category.

Parameters:: visible – The state.

setColor(color: QColor)[source]

Set the color of the context category.

Parameters:: color – The color of the context category.

showContextCategory()[source]: Show the given category, if it is not a context category, nothing happens.

class pyqtribbon.category.RibbonNormalCategory(title: str, parent: QWidget)[source]

Bases: RibbonCategory

A normal category.

Create a new normal category.

Parameters:

title – The title of the category.
parent – The parent widget.

setCategoryStyle(style: RibbonCategoryStyle)[source]

Set the button style of the category.

Parameters:: style – The button style.

pyqtribbon.constants module

class pyqtribbon.constants.RibbonButtonStyle(value)[source]

Bases: IntEnum

Button style, Small, Medium, or Large.

Large = 2[source]

Medium = 1[source]

Small = 0[source]

class pyqtribbon.constants.RibbonCategoryStyle(value)[source]

Bases: IntEnum

The button style of a category.

Context = 1[source]

Normal = 0[source]

class pyqtribbon.constants.RibbonSpaceFindMode(value)[source]

Bases: IntEnum

Mode to find available space in a grid layout, ColumnWise or RowWise.

ColumnWise = 0[source]

RowWise = 1[source]

class pyqtribbon.constants.RibbonStyle(value)[source]

Bases: IntEnum

An enumeration.

Debug = 1[source]

Default = 0[source]

pyqtribbon.constants.contextColors = [<PyQt5.QtGui.QColor object>, <PyQt5.QtGui.QColor object>, <PyQt5.QtGui.QColor object>, <PyQt5.QtGui.QColor object>, <PyQt5.QtGui.QColor object>, <PyQt5.QtGui.QColor object>][source]: A list of context category colors

pyqtribbon.gallery module

class pyqtribbon.gallery.RibbonGallery(minimumWidth=800, popupHideOnClick=False, parent=None)[source]

class pyqtribbon.gallery.RibbonGallery(parent=None)

Bases: QFrame

A widget that displays a gallery of buttons.

Create a gallery.

Parameters:

minimumWidth – minimum width of the gallery
popupHideOnClick – hide on click flag
parent – parent widget

addButton(text: str | None = None, icon: QIcon | None = None, slot=None, shortcut=None, tooltip=None, statusTip=None, checkable=False) → RibbonToolButton[source]

Add a button to the gallery

Parameters:

text – text of the button
icon – icon of the button
slot – slot to call when the button is clicked
shortcut – shortcut of the button
tooltip – tooltip of the button
statusTip – status tip of the button
checkable – checkable flag of the button.

Returns:

the button added

addToggleButton(text: str | None = None, icon: QIcon | None = None, slot=None, shortcut=None, tooltip=None, statusTip=None) → RibbonToolButton[source]

Add a toggle button to the gallery

Parameters:

text – text of the button
icon – icon of the button
slot – slot to call when the button is clicked
shortcut – shortcut of the button
tooltip – tooltip of the button
statusTip – status tip of the button.

Returns:

the button added

hidePopupWidget()[source]: Hide the popup window

popupMenu() → RibbonPermanentMenu[source]: Return the popup menu.

popupWindowSize()[source]

Return the size of the popup window

Returns:: size of the popup window

resizeEvent(a0: QResizeEvent) → None[source]: Resize the gallery.

setPopupHideOnClick(popupHideOnClick: bool)[source]

Set the hide on click flag

Parameters:: popupHideOnClick – hide on click flag

setPopupWindowSize(size: QSize)[source]

Set the size of the popup window

Parameters:: size – size of the popup window

setSelectedButton()[source]: Set the selected button

showPopup()[source]: Show the popup window

class pyqtribbon.gallery.RibbonGalleryButton[source]

Bases: QToolButton

Gallery button.

class pyqtribbon.gallery.RibbonGalleryListWidget(parent=None)[source]

Bases: QListWidget

Gallery list widget.

resizeEvent(e: QResizeEvent) → None[source]: Resize the list widget.

scrollToNextRow() → None[source]: Scroll to the next row.

scrollToPreviousRow() → None[source]: Scroll to the previous row.

class pyqtribbon.gallery.RibbonGalleryPopupListWidget(parent=None)[source]

Bases: RibbonGalleryListWidget

Gallery popup list widget.

class pyqtribbon.gallery.RibbonPopupWidget[source]

Bases: QFrame

The popup widget for the gallery widget.

pyqtribbon.logger module

https://timlehr.com/python-exception-hooks-with-qt-message-box/

class pyqtribbon.logger.UncaughtHook(*args, **kwargs)[source]

Bases: QObject

exception_hook(exc_type, exc_value, exc_traceback)[source]: Function handling uncaught exceptions. It is triggered each time an uncaught exception occurs.

static show_exception_box(log_msg)[source]: Checks if a QApplication instance is available and shows a messagebox with the exception message. If unavailable (non-console application), log an additional notice.

pyqtribbon.menu module

class pyqtribbon.menu.RibbonMenu(title: str = '', parent=None)[source]

class pyqtribbon.menu.RibbonMenu(parent=None)

Bases: QMenu

Create a new panel.

Parameters:

title – The title of the menu.
parent – The parent widget.

addFormLayoutWidget() → QFormLayout[source]

Add a form layout widget to the menu.

Returns:: The form layout.

addGridLayoutWidget() → QGridLayout[source]

Add a grid layout widget to the menu.

Returns:: The grid layout.

addHorizontalLayoutWidget() → QHBoxLayout[source]

Add a horizontal layout widget to the menu.

Returns:: The horizontal layout.

addLabel(text: str = '', alignment=1)[source]

Add a label to the menu.

Parameters:

text – The text of the label.
alignment – The alignment of the label.

addSpacing(spacing: int = 5)[source]

Add spacing to the menu.

Parameters:: spacing – The spacing.

addVerticalLayoutWidget() → QVBoxLayout[source]

Add a vertical layout widget to the menu.

Returns:: The vertical layout.

addWidget(widget: QWidget)[source]

Add a widget to the menu.

Parameters:: widget – The widget to add.

class pyqtribbon.menu.RibbonPermanentMenu(title: str = '', parent=None)[source]

class pyqtribbon.menu.RibbonPermanentMenu(parent=None)

Bases: RibbonMenu

A permanent menu.

Create a new panel.

Parameters:

title – The title of the menu.
parent – The parent widget.

actionAdded(QtWidgets.QAction)[source]

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:: pyqtSignal(*types, name
Type:: str = …, revision

addAction(self, action: QAction | None)[source]

hideEvent(self, a0: QHideEvent | None)[source]

pyqtribbon.panel module

class pyqtribbon.panel.RibbonGridLayoutManager(rows: int)[source]

Bases: object

Grid Layout Manager.

Create a new grid layout manager.

Parameters:: rows – The number of rows in the grid layout.

request_cells(rowSpan: int = 1, colSpan: int = 1, mode=RibbonSpaceFindMode.ColumnWise)[source]

Request a number of available cells from the grid.

Parameters:

rowSpan – The number of rows the cell should span.
colSpan – The number of columns the cell should span.
mode – The mode of the grid.

Returns:

row, col, the row and column of the requested cell.

class pyqtribbon.panel.RibbonPanel(title: str = '', maxRows: int = 6, showPanelOptionButton=True, parent=None)[source]

class pyqtribbon.panel.RibbonPanel(parent=None)

Bases: QFrame

Panel in the ribbon category.

Create a new panel.

Parameters:

title – The title of the panel.
maxRows – The maximal number of rows in the panel.
showPanelOptionButton – Whether to show the panel option button.
parent – The parent widget.

addButton(text: str | None = None, icon: QIcon | None = None, showText: bool = True, slot: Callable | None = None, shortcut: QKeySequence | None = None, tooltip: str | None = None, statusTip: str | None = None, checkable: bool = False, *, rowSpan: RibbonButtonStyle = RibbonButtonStyle.Large, **kwargs) → RibbonToolButton[source]

Add a button to the panel.

Parameters:

text – The text of the button.
icon – The icon of the button.
showText – Whether to show the text of the button.
slot – The slot to call when the button is clicked.
shortcut – The shortcut of the button.
tooltip – The tooltip of the button.
statusTip – The status tip of the button.
checkable – Whether the button is checkable.
rowSpan – The type of the button corresponding to the number of rows it should span.
kwargs – keyword arguments to control the properties of the widget on the ribbon bar.

Returns:

The button that was added.

addCalendarWidget(*args, **kwargs) → QWidget[source]

addComboBox(*args, **kwargs) → QWidget[source]

addDateEdit(*args, **kwargs) → QWidget[source]

addDateTimeEdit(*args, **kwargs) → QWidget[source]

addDoubleSpinBox(*args, **kwargs) → QWidget[source]

addFontComboBox(*args, **kwargs) → QWidget[source]

addGallery(minimumWidth=800, popupHideOnClick=False, **kwargs) → RibbonGallery[source]

Add a gallery to the panel.

Parameters:

minimumWidth – The minimum width of the gallery.
popupHideOnClick – Whether the gallery popup should be hidden when a user clicks on it.
kwargs – keyword arguments to control the properties of the widget on the ribbon bar.

Returns:

The gallery.

addHorizontalSeparator(*, orientation=1, width=6, **kwargs) → RibbonSeparator[source]

addLabel(*args, **kwargs) → QWidget[source]

addLargeButton(text: str = None, icon: QIcon = None, showText: bool = True, slot: Callable = None, shortcut: QKeySequence = None, tooltip: str = None, statusTip: str = None, checkable: bool = False, *, rowSpan: RibbonButtonStyle = RibbonButtonStyle.Large, **kwargs) → RibbonToolButton[source]

addLargeToggleButton(text: str = None, icon: QIcon = None, showText: bool = True, slot: Callable = None, shortcut: QKeySequence = None, tooltip: str = None, statusTip: str = None, *, checkable: bool = True, rowSpan: RibbonButtonStyle = RibbonButtonStyle.Large, **kwargs) → RibbonToolButton[source]

addLargeWidget(widget: QWidget, *, rowSpan: int | RibbonButtonStyle = RibbonButtonStyle.Large, colSpan: int = 1, mode=RibbonSpaceFindMode.ColumnWise, alignment=132, fixedHeight: bool | float = False) → QWidget | Any[source]

addLineEdit(*args, **kwargs) → QWidget[source]

addListWidget(*args, **kwargs) → QWidget[source]

addMediumButton(text: str = None, icon: QIcon = None, showText: bool = True, slot: Callable = None, shortcut: QKeySequence = None, tooltip: str = None, statusTip: str = None, checkable: bool = False, *, rowSpan: RibbonButtonStyle = RibbonButtonStyle.Medium, **kwargs) → RibbonToolButton[source]

addMediumToggleButton(text: str = None, icon: QIcon = None, showText: bool = True, slot: Callable = None, shortcut: QKeySequence = None, tooltip: str = None, statusTip: str = None, *, checkable: bool = True, rowSpan: RibbonButtonStyle = RibbonButtonStyle.Medium, **kwargs) → RibbonToolButton[source]

addMediumWidget(widget: QWidget, *, rowSpan: int | RibbonButtonStyle = RibbonButtonStyle.Medium, colSpan: int = 1, mode=RibbonSpaceFindMode.ColumnWise, alignment=132, fixedHeight: bool | float = False) → QWidget | Any[source]

addPlainTextEdit(*args, **kwargs) → QWidget[source]

addProgressBar(*args, **kwargs) → QWidget[source]

addSeparator(orientation=2, width=6, **kwargs) → RibbonSeparator[source]

Add a separator to the panel.

Parameters:

orientation – The orientation of the separator.
width – The width of the separator.
kwargs – keyword arguments to control the properties of the widget on the ribbon bar.

Returns:

The separator.

addSlider(*args, **kwargs) → QWidget[source]

addSmallButton(text: str = None, icon: QIcon = None, showText: bool = True, slot: Callable = None, shortcut: QKeySequence = None, tooltip: str = None, statusTip: str = None, checkable: bool = False, *, rowSpan: RibbonButtonStyle = RibbonButtonStyle.Small, **kwargs) → RibbonToolButton[source]

addSmallToggleButton(text: str = None, icon: QIcon = None, showText: bool = True, slot: Callable = None, shortcut: QKeySequence = None, tooltip: str = None, statusTip: str = None, *, checkable: bool = True, rowSpan: RibbonButtonStyle = RibbonButtonStyle.Small, **kwargs) → RibbonToolButton[source]

addSmallWidget(widget: QWidget, *, rowSpan: int | RibbonButtonStyle = RibbonButtonStyle.Small, colSpan: int = 1, mode=RibbonSpaceFindMode.ColumnWise, alignment=132, fixedHeight: bool | float = False) → QWidget | Any[source]

addSpinBox(*args, **kwargs) → QWidget[source]

addTableWidget(*args, **kwargs) → QWidget[source]

addTextEdit(*args, **kwargs) → QWidget[source]

addTimeEdit(*args, **kwargs) → QWidget[source]

addToggleButton(text: str = None, icon: QIcon = None, showText: bool = True, slot: Callable = None, shortcut: QKeySequence = None, tooltip: str = None, statusTip: str = None, *, checkable: bool = True, rowSpan: RibbonButtonStyle = RibbonButtonStyle.Large, **kwargs) → RibbonToolButton[source]

addTreeWidget(*args, **kwargs) → QWidget[source]

addVerticalSeparator(*, orientation=2, width=6, **kwargs) → RibbonSeparator[source]

addWidget(widget: QWidget, *, rowSpan: int | RibbonButtonStyle = RibbonButtonStyle.Small, colSpan: int = 1, mode=RibbonSpaceFindMode.ColumnWise, alignment=132, fixedHeight: bool | float = False) → QWidget | Any[source]

Add a widget to the panel.

Parameters:

widget – The widget to add.
rowSpan – The number of rows the widget should span, 2: small, 3: medium, 6: large.
colSpan – The number of columns the widget should span.
mode – The mode to find spaces.
alignment – The alignment of the widget.
fixedHeight – Whether to fix the height of the widget, it can be a boolean, a percentage or a fixed height, when a boolean is given, the height is fixed to the maximum height allowed if the value is True, when a percentage is given (0 < percentage < 1) the height is calculated from the height of the maximum height allowed, depends on the number of rows to span. The minimum height is 40% of the maximum height allowed.

Returns:

The added widget.

addWidgetsBy(data: Dict[str, Dict]) → Dict[str, QWidget][source]

Add widgets to the panel.

Parameters:

data –

The data to add. The dict is of the form:

{
    "widget-name": {
        "type": "Button",
        "arguments": {
            "key1": "value1",
            "key2": "value2"
        }
    },
}

Possible types are: Button, SmallButton, MediumButton, LargeButton, ToggleButton, SmallToggleButton, MediumToggleButton, LargeToggleButton, ComboBox, FontComboBox, LineEdit, TextEdit, PlainTextEdit, Label, ProgressBar, SpinBox, DoubleSpinBox, DataEdit, TimeEdit, DateTimeEdit, TableWidget, TreeWidget, ListWidget, CalendarWidget, Separator, HorizontalSeparator, VerticalSeparator, Gallery.

Returns:

A dictionary of the added widgets.

defaultRowSpan(rowSpan: int | RibbonButtonStyle) → int[source]

Return the number of span rows for the given widget type.

Parameters:: rowSpan – row span or type.
Returns:: The number of span rows for the given widget type.

largeRows() → int[source]

Return the number of span rows for large widgets.

Returns:: The number of span rows for large widgets.

maximumRows() → int[source]

Return the maximal number of rows in the panel.

Returns:: The maximal number of rows in the panel.

mediumRows() → int[source]

Return the number of span rows for medium widgets.

Returns:: The number of span rows for medium widgets.

panelOptionButton() → RibbonPanelOptionButton[source]

Return the panel option button.

Returns:: The panel option button.

panelOptionClicked(bool)[source]

int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

Type:: pyqtSignal(*types, name
Type:: str = …, revision

removeWidget(widget: QWidget)[source]: Remove a widget from the panel.

ribbonArguments = ['rowSpan', 'colSpan', 'mode', 'alignment', 'fixedHeight'][source]

rowHeight() → int[source]: Return the height of a row.

setLargeRows(rows: int)[source]

Set the number of span rows for large widgets.

Parameters:: rows – The number of span rows for large widgets.

setMaximumRows(maxRows: int)[source]

Set the maximal number of rows in the panel.

Parameters:: maxRows – The maximal number of rows in the panel.

setMediumRows(rows: int)[source]

Set the number of span rows for medium widgets.

Parameters:: rows – The number of span rows for medium widgets.

setPanelOptionToolTip(text: str)[source]

Set the tooltip of the panel option button.

Parameters:: text – The tooltip text.

setSmallRows(rows: int)[source]

Set the number of span rows for small widgets.

Parameters:: rows – The number of span rows for small widgets.

setTitle(title: str)[source]

Set the title of the panel.

Parameters:: title – The title to set.

smallRows() → int[source]

Return the number of span rows for small widgets.

Returns:: The number of span rows for small widgets.

title()[source]

Get the title of the panel.

Returns:: The title.

widget(index: int) → QWidget[source]

Get the widget at the given index.

Parameters:: index – The index of the widget, starting from 0.
Returns:: The widget at the given index.

widgets() → List[QWidget][source]

Get all the widgets in the panel.

Returns:: A list of all the widgets in the panel.

class pyqtribbon.panel.RibbonPanelItemWidget(parent=None)[source]

Bases: QFrame

Widget to display a panel item.

Create a new panel item.

Parameters:: parent – The parent widget.

addWidget(widget)[source]

Add a widget to the panel item.

Parameters:: widget – The widget to add.

class pyqtribbon.panel.RibbonPanelOptionButton[source]

Bases: QToolButton

Button to display the options of a panel.

class pyqtribbon.panel.RibbonPanelTitle[source]

Bases: QLabel

Widget to display the title of a panel.

pyqtribbon.ribbonbar module

class pyqtribbon.ribbonbar.RibbonBar(title: str = 'Ribbon Bar Title', maxRows=6, parent=None)[source]

class pyqtribbon.ribbonbar.RibbonBar(parent=None)

Bases: QMenuBar

The RibbonBar class is the top level widget that contains the ribbon.

Create a new ribbon.

Parameters:

title – The title of the ribbon.
maxRows – The maximum number of rows.
parent – The parent widget of the ribbon.

actionAt(self, a0: QPoint) → QAction | None[source]

actionGeometry(self, a0: QAction | None) → QRect[source]

activeAction(self) → QAction | None[source]

addAction(self, action: QAction | None)[source]
addAction(self, text: str | None) → QAction | None
addAction(self, text: str | None, slot: PYQT_SLOT) → QAction | None

addCategoriesBy(data: Dict[str, Dict]) → Dict[str, RibbonCategory][source]

Add categories from a dict.

Parameters:

data –

The dict of categories. The dict is of the form:

{
    "category-title": {
        "style": RibbonCategoryStyle.Normal,
        "color": QtCore.Qt.red,
        "panels": {
            "panel-title": {
                "showPanelOptionButton": True,
                "widgets": {
                    "widget-name": {
                        "type": "Button",
                        "arguments": {
                            "key1": "value1",
                            "key2": "value2"
                        }
                    },
                }
            },
        },
    }
}

Returns:

A dict of categories of the ribbon.

addCategory(title: str, style=RibbonCategoryStyle.Normal, color: QColor | None = None) → RibbonNormalCategory | RibbonContextCategory[source]

Add a new category to the ribbon.

Parameters:

title – The title of the category.
style – The button style of the category.
color – The color of the context category, only used if style is Context, if None, the default color will be used.

Returns:

The newly created category.

addContextCategories(name: str, titles: List[str], color: QColor | GlobalColor = 9) → RibbonContextCategories[source]

Add a group of context categories with the same tab color to the ribbon.

Parameters:

name – The name of the context categories.
titles – The title of the category.
color – The color of the context category, if None, the default color will be used.

Returns:

The newly created category.

addContextCategory(title: str, color: QColor | GlobalColor = 9) → RibbonContextCategory[source]

Add a new context category to the ribbon.

Parameters:

title – The title of the category.
color – The color of the context category, if None, the default color will be used.

Returns:

The newly created category.

addFileMenu() → RibbonMenu[source]: Add a file menu to the ribbon.

addMenu(self, menu: QMenu | None) → QAction | None[source]
addMenu(self, title: str | None) → QMenu | None
addMenu(self, icon: QIcon, title: str | None) → QMenu | None

addNormalCategory(title: str) → RibbonNormalCategory[source]

Add a new category to the ribbon.

Parameters:: title – The title of the category.
Returns:: The newly created category.

addQuickAccessButton(button: QToolButton)[source]

Add a button to the quick access bar.

Parameters:: button – The button to add.

addRightToolButton(button: QToolButton)[source]

Add a widget to the right button bar.

Parameters:: button – The button to add.

addSeparator(self) → QAction | None[source]

addTitleWidget(widget: QWidget)[source]

Add a widget to the title widget.

Parameters:: widget – The widget to add.

applicationOptionButton() → RibbonApplicationButton[source]: Return the application button.

categories() → Dict[str, RibbonCategory][source]

Return a list of categories of the ribbon.

Returns:: A dict of categories of the ribbon.

category(name: str) → RibbonCategory[source]

Return the category with the given name.

Parameters:: name – The name of the category.
Returns:: The category with the given name.

categoryVisible(category: RibbonCategory) → bool[source]

Return whether the category is shown.

Parameters:: category – The category to check.
Returns:: Whether the category is shown.

clear(self)[source]

collapseRibbonButton() → QToolButton[source]

Return the collapse ribbon button.

Returns:: The collapse ribbon button.

cornerWidget(self, corner: Corner = Qt.TopRightCorner) → QWidget | None[source]

currentCategory() → RibbonCategory[source]

Return the current category.

Returns:: The current category.

eventFilter(self, a0: QObject | None, a1: QEvent | None) → bool[source]

helpButtonClicked(bool)[source]: Signal, the help button was clicked.

helpRibbonButton() → QToolButton[source]

Return the help button of the ribbon.

Returns:: The help button of the ribbon.

hideContextCategory(category: RibbonContextCategory | RibbonContextCategories)[source]

Hide the given category or categories, if it is not a context category, nothing happens.

Parameters:: category – The category to hide.

hideRibbon()[source]: Hide the ribbon.

insertMenu(self, before: QAction | None, menu: QMenu | None) → QAction | None[source]

insertSeparator(self, before: QAction | None) → QAction | None[source]

insertTitleWidget(index: int, widget: QWidget)[source]

Insert a widget to the title widget.

Parameters:

index – The index to insert the widget.
widget – The widget to insert.

isDefaultUp(self) → bool[source]

isNativeMenuBar(self) → bool[source]

minimumSizeHint() → QSize[source]

Return the minimum size hint of the widget.

Returns:: The minimum size hint.

quickAccessToolBar() → QToolBar[source]

Return the quick access toolbar of the ribbon.

Returns:: The quick access toolbar of the ribbon.

removeCategories(categories: RibbonContextCategories)[source]

Remove a list of categories from the ribbon.

Parameters:: categories – The categories to remove.

removeCategory(category: RibbonCategory)[source]

Remove a category from the ribbon.

Parameters:: category – The category to remove.

removeCollapseButton()[source]: Remove the min button from the ribbon.

removeHelpButton()[source]: Remove the help button from the ribbon.

removeTitleWidget(widget: QWidget)[source]

Remove a widget from the title widget.

Parameters:: widget – The widget to remove.

ribbonHeight() → int[source]

Get the total height of the ribbon.

Returns:: The height of the ribbon.

ribbonVisible() → bool[source]

Get the visibility of the ribbon.

Returns:: True if the ribbon is visible, False otherwise.

rightToolBar() → QToolBar[source]

Return the right toolbar of the ribbon.

Returns:: The right toolbar of the ribbon.

setActiveAction(self, action: QAction | None)[source]

setApplicationIcon(icon: QIcon)[source]

Set the application icon.

Parameters:: icon – The icon to set.

setAutoHideRibbon(autoHide: bool)[source]

Set whether the ribbon bar is automatically hidden when the mouse is pressed outside the ribbon bar.

Parameters:: autoHide – Whether the ribbon bar is automatically hidden.

setCollapseButtonIcon(icon: QIcon)[source]

Set the icon of the min button.

Parameters:: icon – The icon to set.

setCornerWidget(self, widget: QWidget | None, corner: Corner = Qt.TopRightCorner)[source]

setCurrentCategory(category: RibbonCategory)[source]

Set the current category.

Parameters:: category – The category to set.

setDefaultUp(self, a0: bool)[source]

setHelpButtonIcon(icon: QIcon)[source]

Set the icon of the help button.

Parameters:: icon – The icon to set.

setNativeMenuBar(self, nativeMenuBar: bool)[source]

setQuickAccessButtonHeight(height: int = 30)[source]

Set the height of the quick access buttons.

Parameters:: height – The height to set.

setRibbonHeight(height: int)[source]

Set the total height of the ribbon.

Parameters:: height – The height to set.

setRibbonStyle(style: RibbonStyle)[source]

Set the style of the ribbon.

Parameters:: style – The style to set.

setRibbonVisible(visible: bool)[source]

Set the visibility of the ribbon.

Parameters:: visible – True to show the ribbon, False to hide it.

setRightToolBarHeight(height: int = 24)[source]

Set the height of the right buttons.

Parameters:: height – The height to set.

setTitle(title: str)[source]

Set the title of the ribbon.

Parameters:: title – The title to set.

showCategoryByIndex(index: int)[source]

Show category by tab index

Parameters:: index – tab index

showContextCategory(category: RibbonContextCategory | RibbonContextCategories)[source]

Show the given category or categories, if it is not a context category, nothing happens.

Parameters:: category – The category to show.

showRibbon()[source]: Show the ribbon.

tabBar() → RibbonTabBar[source]

Return the tab bar of the ribbon.

Returns:: The tab bar of the ribbon.

title() → str[source]

Return the title of the ribbon.

Returns:: The title of the ribbon.

class pyqtribbon.ribbonbar.RibbonStackedWidget(parent=None)[source]

Bases: QStackedWidget

Stacked widget that is used to display the ribbon.

Create a new ribbon stacked widget.

Parameters:: parent – The parent widget.

pyqtribbon.screenshotwindow module

class pyqtribbon.screenshotwindow.RibbonScreenShotWindow(fileName: str = 'shot.jpg', *args, **kwargs)[source]

Bases: QMainWindow

This class is just for taking a screenshot of the window, the window will be closed 0.1s after it is shown.

Initialize the class.

Parameters:: fileName – The file name for the screenshot.

setScreenShotFileName(fileName: str)[source]

Set the file name for the screenshot.

Parameters:: fileName – The file name for the screenshot.

takeScreenShot()[source]: Take a screenshot of the window.

pyqtribbon.separator module

class pyqtribbon.separator.RibbonHorizontalSeparator(width: int = 6, parent=None)[source]

Bases: RibbonSeparator

Horizontal separator.

Create a new horizontal separator.

Parameters:

width – The width of the separator.
parent – The parent widget.

class pyqtribbon.separator.RibbonSeparator(orientation=QtCore.Qt.Vertical, width=6, parent=None)[source]

class pyqtribbon.separator.RibbonSeparator(parent=None)

Bases: QFrame

The RibbonSeparator is a separator that can be used to separate widgets in a ribbon.

Create a new separator.

Parameters:

orientation – The orientation of the separator.
width – The width of the separator.
parent – The parent widget.

paintEvent(event: QPaintEvent) → None[source]: Paint the separator.

setTopBottomMargins(top: int, bottom: int) → None[source]: Set the top and bottom margins.

sizeHint() → QSize[source]: Return the size hint.

class pyqtribbon.separator.RibbonVerticalSeparator(width: int = 6, parent=None)[source]

Bases: RibbonSeparator

Vertical separator.

Create a new vertical separator.

Parameters:

width – The width of the separator.
parent – The parent widget.

pyqtribbon.tabbar module

class pyqtribbon.tabbar.RibbonTabBar(parent=None)[source]

Bases: QTabBar

The TabBar for the title widget.

Create a new tab bar.

Parameters:: parent – The parent widget.

addAssociatedTabs(name: str, texts: List[str], color: QColor) → List[int][source]

Add associated multiple tabs which have the same color to the tab bar.

Parameters:

name – The name of the context category.
texts – The texts of the tabs.
color – The color of the tabs.

Returns:

The indices of the tabs.

addTab(text: str, color: QColor | None = None, *args, **kwargs) → int[source]

Add a new tab to the tab bar.

Parameters:

text – The text of the tab.
color – The color of the tab.

Returns:

The index of the tab.

changeColor(inx: int) → None[source]: Change tab’s color.

currentTabColor() → QColor[source]

Current tab color

Returns:: Current tab color

indexOf(tabName: str) → int[source]

Return the index of the tab with the given name.

Parameters:: tabName – The name of the tab.
Returns:: The index of the tab.

removeAssociatedTabs(titles: List[str]) → None[source]

Remove tabs with the given titles.

Parameters:: titles – The titles of the tabs to remove.

tabTitles() → List[str][source]

Return the titles of all tabs.

Returns:: The titles of all tabs.

pyqtribbon.titlewidget module

class pyqtribbon.titlewidget.RibbonApplicationButton[source]

Bases: QToolButton

Application button in the ribbon bar.

addFileMenu() → RibbonMenu[source]

Add a new ribbon menu to the application button.

Returns:: The new ribbon menu.

class pyqtribbon.titlewidget.RibbonTitleLabel[source]

Bases: QLabel

Title label in the ribbon bar.

class pyqtribbon.titlewidget.RibbonTitleWidget(title='PyQtRibbon', parent=None)[source]

class pyqtribbon.titlewidget.RibbonTitleWidget(parent=None)

Bases: QFrame

The title widget of the ribbon.

Initialize the ribbon title widget.

Parameters:

title – The title of the ribbon.
parent – The parent widget.

addQuickAccessButton(button: QToolButton)[source]

Add a widget to the quick access bar.

Parameters:: button – The button to add.

addRightToolButton(button: QToolButton)[source]

Add a widget to the right button bar.

Parameters:: button – The button to add.

addTitleWidget(widget: QWidget)[source]

Add a widget to the title layout.

Parameters:: widget – The widget to add.

applicationButton() → RibbonApplicationButton[source]: Return the application button.

collapseRibbonButton() → QToolButton[source]

Return the collapse ribbon button.

Returns:: The collapse ribbon button.

collapseRibbonButtonClicked(bool)[source]: Signal, the collapse button wa clicked.

helpButtonClicked(bool)[source]: Signal, the help button was clicked.

helpRibbonButton() → QToolButton[source]

Return the help ribbon button.

Returns:: The help ribbon button.

insertTitleWidget(index: int, widget: QWidget)[source]

Insert a widget to the title layout.

Parameters:

index – The index to insert the widget.
widget – The widget to insert.

mouseDoubleClickEvent(self, a0: QMouseEvent | None)[source]

mouseMoveEvent(self, a0: QMouseEvent | None)[source]

mousePressEvent(self, a0: QMouseEvent | None)[source]

quickAccessButtons() → List[QToolButton][source]

Return the quick access buttons of the ribbon.

Returns:: The quick access buttons of the ribbon.

quickAccessToolBar() → QToolBar[source]

Return the quick access toolbar of the ribbon.

Returns:: The quick access toolbar of the ribbon.

removeCollapseButton()[source]: Remove the min button from the ribbon.

removeHelpButton()[source]: Remove the help button from the ribbon.

removeTitleWidget(widget: QWidget)[source]

Remove a widget from the title layout.

Parameters:: widget – The widget to remove.

rightToolBar() → QToolBar[source]

Return the right toolbar of the ribbon.

Returns:: The right toolbar of the ribbon.

setApplicationIcon(icon: QIcon)[source]

Set the application icon.

Parameters:: icon – The icon to set.

setCollapseButtonIcon(icon: QIcon)[source]

Set the icon of the min button.

Parameters:: icon – The icon to set.

setHelpButtonIcon(icon: QIcon)[source]

Set the icon of the help button.

Parameters:: icon – The icon to set.

setQuickAccessButtonHeight(height: int = 30)[source]

Set the height of the quick access buttons.

Parameters:: height – The height to set.

setRightToolBarHeight(height: int = 24)[source]

Set the height of the right buttons.

Parameters:: height – The height to set.

setTitle(title: str)[source]

Set the title of the ribbon.

Parameters:: title – The title to set.

tabBar() → RibbonTabBar[source]

Return the tab bar of the ribbon.

Returns:: The tab bar of the ribbon.

title() → str[source]

Return the title of the ribbon.

Returns:: The title of the ribbon.

topLevelWidget() → QWidget[source]

pyqtribbon.toolbutton module

class pyqtribbon.toolbutton.RibbonToolButton(parent=None)[source]

Bases: QToolButton

Tool button that is showed in the ribbon.

Create a new ribbon tool button.

Parameters:: parent – The parent widget.

addRibbonMenu() → RibbonMenu[source]

Add a ribbon menu for the button.

Returns:: The added ribbon menu.

buttonStyle() → RibbonButtonStyle[source]

Get the button style of the button.

Returns:: The button style of the button.

maximumIconSize() → int[source]

Get the maximum icon size of the button.

Returns:: The maximum icon size of the button.

setButtonStyle(style: RibbonButtonStyle)[source]

Set the button style of the button.

Parameters:: style – The button style of the button.

setMaximumIconSize(size: int)[source]

Set the maximum icon size of the button.

Parameters:: size – The maximum icon size of the button.

pyqtribbon.utils module

pyqtribbon.utils.DataFile(filename)[source]

Return the path to a data file.

Parameters:: filename – The filename of the data file.
Returns:: The path to the data file.

Welcome to PyQtRibbon’s documentation!

Getting Started

Installation

The Ribbon Bar

Introduction

Definitions of Ribbon Elements

Ribbon Elements in PyQtRibbon

User Manual

The RibbonScreenShotWindow Class

Instantiate a Ribbon Bar

Example

Customize Ribbon Bar

General Setups

Setup Application Button

Setup Title

Setup Category Tab Bar

Setup Quick Access Bar

Setup Right Tool Bar

Example

Manage Categories

Customize Categories

Setup Styles

Manage Panels

Example

Customize Panels

Setup Title Label

Setup Panel Option Button

Add Widgets to Panels

Example

A Complete Example

API References

pyqtribbon package

Submodules

pyqtribbon.category module

pyqtribbon.constants module

pyqtribbon.gallery module

pyqtribbon.logger module

pyqtribbon.menu module

pyqtribbon.panel module

pyqtribbon.ribbonbar module

pyqtribbon.screenshotwindow module

pyqtribbon.separator module

pyqtribbon.tabbar module

pyqtribbon.titlewidget module

pyqtribbon.toolbutton module

pyqtribbon.utils module

pyqtribbon.version module

Module contents

Indices and tables