| Windows(latest) | Linux ubuntu(latest) | Mac(latest) | |
|---|---|---|---|
| Qt5.12 LTS | |||
| Qt5.14 | |||
| Qt5.15 LTS | |||
| Qt6.2 LTS | |||
| Qt6.5 LTS | |||
| Qt6.8 LTS |
This is a Qt-based Ribbon interface widget that provides an operation interface similar to Microsoft Office software.
SARibbonis suitable for the UI of large-scale software, industrial software, and complex software.SARibbonreferences the naming style of the MFC Ribbon interface in its design.SARibbondraws on the Ribbon interfaces of Microsoft Office and WPS software, combining the strengths of both.SARibbonis a Ribbon widget that can define multiple theme styles and quickly define desired themes through qss.
For the convenience of developing large-scale software, SARibbon encapsulates some commonly used functional widgets, such as color selection buttons and color selection palettes.
- Ribbon layout and display
- Support for minimized mode, where the Ribbon only displays tabs (double-clicking a tab will toggle by default), and support for context tab.
- Support for quickAccessBar (similar to Word's quick menu), which has different display effects under different layout modes.
- Support for 4 types of Ribbon buttons: regular buttons, delayed pop-up menu buttons, menu buttons, and action menu buttons (the action menu button is one of the main issues this Ribbon widget addresses).
- Support for 4 different styles of layout.
- Support for customizing the Ribbon using qss, with real-time theme switching and 5 built-in different styles.
Win7 theme:
Office2013 theme:
Office2016 theme:
Office2021 theme:
Dark theme:
- Provide Gallery widget.
- Support for long scrolling and Option Action.
- Provide center alignment mode.
- Support for 4K screens and multi-screen extension.
- Support for Linux and MacOS (the interface is not deeply customized).
Under the MIT license, everyone is welcome to use it and provide feedback.
gitee (Code Cloud) - https://gitee.com/czyt1988/SARibbon
github - https://github.com/czyt1988/SARibbon
It is recommended to use cmake for building. After completing the cmake build and installation, your project can integrate SARibbonBar using either cmake or qmake.
SARibbon offers both qmake and cmake build options. Additionally, it provides integrated SARibbon.h and SARibbon.cpp files for quick static embedding in projects.
SARibbon supports the third-party frameless library QWindowkit. It also supports a simple frameless solution. If you need native window support from the operating system, such as edge snapping in Windows 7 and later, or the maximize button hover effect in Windows 11, it is recommended to enable the QWindowkit library. The QWindowkit library can also better solve multi-screen movement issues.
The effect after enabling QWindowkit is as follows:
If you want to depend on the QWindowkit library, you need to compile the QWindowkit library first. As a submodule of the SARibbon project, if the --recursive parameter was not included during git clone, you need to run the submodule update command:
git submodule update --init --recursiveAfter the user specifies the use of QWindowkit, the minimum C++ standard required is C++17, otherwise the minimum requirement is C++14.
For the specific build process, refer to the document: SARibbon Build
You can integrate SARibbon without building it into a dynamic library by directly including the provided SARibbon.h and SARibbon.cpp files in your project. These files include all necessary resources. Refer to the StaticExample (located in example/StaticExample) for guidance.
To use qmake, follow these steps:
- Copy
SARibbon.h,SARibbon.cpp, andSARibbon.pri(from the./srcdirectory) to your project directory. - Include the
SARibbon.prifile in your project's pro file, like:include($$PWD/SARibbon.pri).
qmake can use the SARibbon.pri file to configure whether to enable the third-party frameless library.
When using cmake, refer to the cmake writing style in the StaticExample (located in example/StaticExample). Simply include SARibbon.h and SARibbon.cpp in your project.
set(SARIBBON_FILES
SARibbon.h
SARibbon.cpp
)
add_executable({your-target}
{your project's cpp and header files}
${SARIBBON_FILES}
)If your project needs to use QWindowkit, you must integrate the QWindowkit library and add the pre-defined macro:
find_package(QWindowKit)
target_link_libraries({your-target} PRIVATE QWindowKit::Widgets)
target_compile_definitions({your-target} PRIVATE SARIBBON_USE_3RDPARTY_FRAMELESSHELPER=1)Otherwise, you need to set it to 0:
target_compile_definitions({your-target} PRIVATE SARIBBON_USE_3RDPARTY_FRAMELESSHELPER=0)After compilation, integrate SARibbon into your project as follows:
- Copy
SARibbon.h,SARibbon.cpp, andSARibbon.pri(from the./srcdirectory) to your project directory. - Include
SARibbon.priin your project's .pro file:include($$PWD/SARibbon.pri).
Refer to the comments in SARibbon.pri for configuration details.
If you've built SARibbon dynamically, use it after installation via:
set(SARibbonBar_DIR "[Your SARibbonBar install root]/lib/cmake")
find_package(SARibbonBar REQUIRED)
target_link_libraries({your_target_name} PUBLIC SARibbonBar::SARibbonBar)The Ribbon combines the menu bar and toolbar, displaying them through a tab widget. The Ribbon cannot be simply replaced by a Tab+Toolbar, as it involves many detailed issues. When designing SARibbon, the naming style of the MFC Ribbon interface was referenced. The tab page is called Category (kind), and each Category has multiple pannel (panels) under it, which manage toolbuttons. The pannel is somewhat similar to a traditional Toolbar. The hierarchy is shown in the figure below, and these names reference the Ribbon interface classes in MFC.
Some common terminology explanations are as follows:
- Category: Represents the content displayed by a tab, corresponding to
SARibbonCategory. - Context Category: This is a special kind of category that is not displayed normally and is shown based on context. The most common example is in Word, where a picture editing-related tab appears when an image is selected, and disappears when the image is deselected. This is a context category, corresponding to
SARibbonContextCategory. - Pannel: A collection of menus, similar to a Toolbar, corresponding to
SARibbonPannel. - Application Button: The button at the top-left corner of the tab bar (in Word, it corresponds to the File button). This button triggers special pages or menus, corresponding to
SARibbonApplicationButton, which can be hidden. - Quick Access Bar: A simple toolbar at the very top for placing frequently used actions, corresponding to
SARibbonQuickAccessBar. - Gallery: This is the most eye-catching widget of the Ribbon, displaying functions with intuitive images. Some even render in real-time based on context. A typical example is the style selection in the Home tab of Word, corresponding to
SARibbonGallery.
The hierarchy of SARibbonBar is shown in the figure below:
Note: Different layout schemes affect the placement of
CategoryandQuick Access Bar. For more details, see [SARibbonBar Layout Schemes](#SARibbonBar Layout Schemes).
To use SARibbon in MainWindow, you need to replace QMainWindow with SARibbonMainWindow. SARibbonMainWindow modifies the rendering of the menubar in QMainWindow.
Note: If you are using a ui file, delete the original menu in the ui file to avoid potential exceptions, as shown in the figure below:
Example code is as follows:
#include "SARibbonMainWindow.h"
class MainWindow : public SARibbonMainWindow
{
Q_OBJECT
public:
MainWindow(QWidget* par = nullptr);
...
}SARibbonMainWindow also supports rendering in normal mode. The second parameter of the SARibbonMainWindow constructor is used to set whether to use Ribbon mode:
SARibbonMainWindow(QWidget *parent = nullptr, bool useRibbon = true);If the second parameter is set to false, it will use the normal menu toolbar mode. This interface is reserved for projects that need to switch between Ribbon and classic menu toolbar modes. Ribbon state and classic state do not support hot switching. If switching is needed, users can set a configuration file or registry entry and pass false to the second parameter upon application restart to enter the classic menu toolbar mode.
SARibbonBar supports use in QWidget or QDialog. For more details, see the example: example/WidgetWithRibbon.
The project provides the SARibbonWidget class. Inheriting SARibbonWidget in a widget window will achieve a Ribbon-effect window.
#include "SARibbonWidget.h"
class RibbonWidget : public SARibbonWidget
{
Q_OBJECT
public:
RibbonWidget(QWidget* parent = nullptr);
};The SARibbonWidget class provides the setWidget method, which can embed any widget.
RibbonWidget::RibbonWidget(QWidget* parent) : SARibbonWidget(parent)
{
// Get SARibbonBar
SARibbonBar* ribbonbar = ribbonBar();
// In QWidget mode, there is no need to display the title
ribbonbar->setTitleVisible(false);
// In QWidget mode, using compact mode is better
ribbonbar->setRibbonStyle(SARibbonBar::RibbonStyleCompactThreeRow);
// Cancel applicationbutton
ribbonbar->setApplicationButton(nullptr);
setWidget(new InnerWidget());
}The effect is as follows:
The order of creating a Ribbon is as follows: first create the category ( Category), then create the panel (Pannel), and finally create the corresponding toolbutton (action).
Use SARibbonBar::addCategoryPage to add the Category to SARibbonBar, use SARibbonCategory::addPannel to add the Pannel to the Category, and use SARibbonPannel::addAction to add actions to the Pannel.
The following code demonstrates an example of adding an action:
// Add the main tab page - through the addCategoryPage factory function
SARibbonCategory* categoryMain = ribbon->addCategoryPage(tr("Main"));
// Use the addPannel function to create a SARibbonPannel, which has the same effect as creating a new SARibbonPannel and then adding it
SARibbonPannel* pannel1 = categoryMain->addPannel("Panel 1");
QAction* actSave = new QAction(this);
actSave->setText("save");
actSave->setIcon(QIcon(":/icon/icon/save.svg"));
actSave->setObjectName("actSave");
actSave->setShortcut(QKeySequence(QLatin1String("Ctrl+S")));
pannel1->addLargeAction(actSave);The above operation adds a button, and the effect is shown in the figure below:
Users can also directly create a SARibbonCategory and add it to the pannel. The following code has the same effect as the one above:
SARibbonCategory* categoryMain = new SARibbonCategory(tr("Main"));
ribbon->addCategoryPage(categoryMain);
SARibbonPannel* pannel1 = new SARibbonPannel("Panel 1");
categoryMain->addPannel(pannel1);
QAction* actSave = new QAction(this);
...
pannel1->addLargeAction(actSave);Ribbon icons come in different sizes. Using addLargeAction, addMediumAction, and addSmallAction can create different layout styles.
For more details, see ./example/MainWindowExample/mainwindow.cpp.
Contextual tabs are special tabs or tab groups that only appear under certain conditions. For example, in Microsoft Office Word, when an image is selected, an image editing contextual tab appears. If no image is selected, the tab disappears. This is a contextual tab, corresponding to SARibbonContextCategory.
Contextual tabs are usually created during program initialization and hidden by default, waiting to be displayed when needed. Creating a contextual tab is as follows:
Since contextual tabs need to be invoked when needed, it is a good practice to save them as member variables. Of course, you can also search for them by iterating through the list (using SARibbonBar::contextCategoryList to enumerate all SARibbonContextCategory instances).
Header file:
SARibbonContextCategory* m_contextCategory;Cpp file:
SARibbonBar* ribbon = ribbonBar();
// Create a contextCategory with a random color
m_contextCategory = ribbon->addContextCategory(tr("context"), QColor());
SARibbonCategory* contextCategoryPage1 = m_contextCategory->addCategoryPage(tr("Page1"));
// Perform operations on contextCategoryPage1
......
SARibbonCategory* contextCategoryPage2 = m_contextCategory->addCategoryPage(tr("Page2"));
// Perform operations on contextCategoryPage2
......SARibbonCategory instances created by SARibbonContextCategory are managed by SARibbonContextCategory. Only when SARibbonContextCategory is "displayed" will its managed SARibbonCategory instances be shown. Note: SARibbonContextCategory is not a window.
To display a contextual tab, simply call SARibbonBar::showContextCategory or SARibbonBar::hideContextCategory:
void MainWindow::onShowContextCategory(bool on)
{
if (on) {
this->ribbonBar()->showContextCategory(m_contextCategory);
} else {
this->ribbonBar()->hideContextCategory(m_contextCategory);
}
}Note: If you need to delete a contextCategory, call SARibbonBar::destroyContextCategory instead of directly deleting it. After calling SARibbonBar::destroyContextCategory, there is no need to delete the pointer to ContextCategory.
Different styles of contextCategory have different appearances. For more details, see [SARibbon Styles](#SARibbon Styles) and [Comparison of Appearance Under Different Styles](#Comparison of Appearance Under Different Styles).
There is a special and prominent button at the top-left corner of the Ribbon interface, known as the applicationButton. This button is generally used to invoke a menu. By default, SARibbonBar creates an applicationButton during construction, and you can set its text as follows:
SARibbonBar* ribbon = ribbonBar();
ribbon->applicationButton()->setText(("File"));The default applicationButton inherits from SARibbonApplicationButton, which in turn inherits from QPushButton. Therefore, you can perform all operations available for QPushButton on it. If you wish to set your own button as the applicationButton, you can do so by calling the SARibbonBar::setApplicationButton function.
The QuickAccessBar is a simple toolbar located at the top-left corner, while the rightButtonGroup is a toolbar at the top-right corner. In Office mode, these toolbars are separated into left and right sides, whereas in WPS mode, they are combined and placed on the right side.
In SARibbon:
- QuickAccessBar corresponds to the
SARibbonQuickAccessBarclass. - rightButtonGroup corresponds to the
SARibbonButtonGroupWidgetclass.
SARibbonBar initializes by default with QuickAccessBar and RightButtonGroup. You can obtain pointers to these components and perform operations on them using SARibbonBar::quickAccessBar and SARibbonBar::rightButtonGroup, respectively. Here is an example:
QAction* MainWindow::createAction(const QString& text, const QString& iconurl, const QString& objName)
{
QAction* act = new QAction(this);
act->setText(text);
act->setIcon(QIcon(iconurl));
act->setObjectName(objName);
return act;
}
void MainWindow::initQuickAccessBar(){
SARibbonBar* ribbon = ribbonBar();
SARibbonQuickAccessBar* quickAccessBar = ribbon->quickAccessBar();
quickAccessBar->addAction(createAction("save", ":/icon/icon/save.svg", "save-quickbar"));
quickAccessBar->addSeparator();
quickAccessBar->addAction(createAction("undo", ":/icon/icon/undo.svg"),"undo");
quickAccessBar->addAction(createAction("redo", ":/icon/icon/redo.svg"),"redo");
quickAccessBar->addSeparator();
}
void MainWindow::initRightButtonGroup(){
SARibbonBar* ribbon = ribbonBar();
SARibbonButtonGroupWidget* rightBar = ribbon->rightButtonGroup();
QAction* actionHelp = createAction("help", ":/icon/icon/help.svg","help");
connect(actionHelp, &QAction::triggered, this, &MainWindow::onActionHelpTriggered);
rightBar->addAction(actionHelp);
}