Skip to content

SARibbon User Guide

  • ✅ Quick start: Static embedding needs only 2 files, 5 lines of code to create a Ribbon interface
  • ✅ MFC-style naming: Category/Panel/Action naming follows MFC Ribbon conventions
  • ✅ Contextual tabs: SARibbonContextCategory condition-based show/hide for specific feature groups
  • ✅ Gallery widget: Grid-style display for large icon option sets
  • ✅ Customization persistence: User-customizable UI with XML save/load configuration
  • ✅ 12-step documentation: From import to advanced, covering all core features

SARibbon is a Qt library for creating modern Ribbon interfaces, with a style similar to Microsoft Office or WPS. It is designed for complex desktop applications, effectively organizing a large number of functions, and is commonly used in the interface development of industrial software.

Before starting coding, you need to integrate the SARibbon library into your Qt project. The simplest way is static embedding, which is to directly copy the source files SARibbon.h and SARibbon.cpp into your project.

Quick Start

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#include "SARibbon.h"
#include <QApplication>

int main(int argc, char* argv[])
{
#if (QT_VERSION >= QT_VERSION_CHECK(5, 6, 0))
    QApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
    QApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);
#endif
    SARibbonBar::initHighDpi();
    QApplication a(argc, argv);

    SARibbonMainWindow w;
    w.setWindowTitle("SARibbon Quick Start");

    SARibbonBar* ribbon = w.ribbonBar();
    SARibbonCategory* cat = ribbon->addCategoryPage("Home");
    SARibbonPanel* panel = cat->addPanel("Actions");
    panel->addLargeAction(new QAction(QIcon(":/icon.svg"), "Click Me", &w));

    w.show();
    return a.exec();
}

Documentation Reading Guide

Topic Document Description
Building Build Instructions How to build SARibbon (CMake/QMake)
Integration Importing the Library Static/dynamic integration into your project
Window Setup Create a Ribbon-Style Window SARibbonMainWindow / SARibbonWidget usage
UI Creation Creating the Ribbon UI Category, Panel, Action, Gallery, etc.
Layout Ribbon Layout Options Loose/Compact, 2-row/3-row/SingleRow modes
Theming Ribbon Themes Built-in themes and custom QSS styling
Customization User-Configurable Ribbon Runtime customization and XML persistence

Differences between Ribbon interface and traditional menubar+toolbar

The traditional menubar+toolbar cannot be directly converted into a ribbon interface. Ribbon is not just a toolbar with QToolBar. Compared with the traditional menu bar and toolbar, it has the following characteristics:

  • The button rendering method of Ribbon has an obvious change, making it impossible to directly use ToolButton for simulation. SARibbon uses SARibbonToolButton to re-layout and render the buttons for Ribbon.
  • Ribbon also has a special type of tab called Context Category. For example, when you select a picture in Office Word, a "Picture Editing" tab will automatically appear, providing picture-specific functions such as cropping and rotating. This tab will automatically hide when the selection is canceled.
  • The Ribbon interface comes with some special controls, such as Gallery (the style selection in Word is a Gallery control).

Terminology

Term SARibbon Class Description
Ribbon Bar SARibbonBar The main Ribbon control at the top of the window
Category SARibbonCategory A tab page, equivalent to a functional group
Panel SARibbonPanel A group of related actions within a Category
Tool Button SARibbonToolButton Ribbon-specific button with custom painting
Context Category SARibbonContextCategory Conditional tab that appears based on context
Gallery SARibbonGallery Grid-style visual selector (e.g., styles in Word)
Quick Access Bar SARibbonQuickAccessBar Toolbar at the very top for frequently used actions
Application Button SARibbonApplicationButton The "File" button at the top-left corner