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 QtWidgets, QtGui

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.QtWidgets import QApplication
from qtpy.QtGui import QIcon

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.QtWidgets import QApplication, QToolButton, QMenu, QLabel, QLineEdit
from qtpy.QtGui import QIcon
from qtpy.QtCore import Qt

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.QtWidgets import QApplication, QLabel, QWidget, QVBoxLayout
from PyQt5.QtGui import QIcon, QFont
from PyQt5.QtCore import Qt

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: