Это элемент управления Ribbon в рамках фреймворка Qt, который предоставляет интерфейс, аналогичный интерфейсу программного обеспечения Microsoft Office. SARibbon подходит для крупного программного обеспечения, промышленного программного обеспечения и сложного пользовательского интерфейса программного обеспечения.

SARibbon разработан с учётом стиля именования интерфейса MFC Ribbon, а стиль интерфейса SARibbon ссылается на интерфейс Ribbon программного обеспечения серии Microsoft Office и WPS и сочетает в себе преимущества обоих. SARibbon — это виджет ленты, который может определять различные стили тем, и он может быстро определить желаемый стиль темы через qss.

Чтобы облегчить разработку крупного программного обеспечения, SARibbon инкапсулирует некоторые часто используемые функциональные элементы управления, такие как Color Widgets.

Особенности

• Макет и отображение ленты.
• Поддержка режима минимизации, лента показывает только вкладки (по умолчанию двойной щелчок по вкладке переключит режим).
• Поддерживает quickAccessBar (быстрое меню Word), который будет иметь разные эффекты отображения в разных режимах макета. Поддержка 4 различных кнопок ленты: обычные кнопки, кнопки всплывающего меню с задержкой, кнопки меню и кнопки контекстного меню.

Существует 4 разных стиля компоновки ленты.

Поддерживает QSS для настройки ленты, вы можете переключать темы в реальном времени, и есть 5 встроенных различных стилей тем:

• тема win7;
• тема office2013;
• тема office2016;
• тема office2021;
• тёмная тема.

Предоставляет элемент управления «Галерея».

Поддерживает длинную прокрутку и опцию «Действие».

Обеспечивает режим центрированного выравнивания.

Поддержка экрана 4K и нескольких экранов.

Поддержка Linux и MacOS.

Протокол MIT, приглашаем всех использовать и оставлять комментарии.

Gitee — https://gitee.com/czyt1988/SARibbon.

GitHub — https://github.com/czyt1988/SARibbon.

Сборка

SARibbon предоставляет методы сборки qmake и cmake и предоставляет объединённые файлы SARibbon.h и SARibbon.cpp для статического встраивания в один проект.

SARibbon поддерживает стороннюю библиотеку QWindowKit. В то же время он также поддерживает простые безрамочные решения. Если вам нужна поддержка нативных окон для операционной системы, такая как обрезка краёв после Windows 7 и эффект максимизации при наведении кнопок в Windows 11, рекомендуется включить библиотеку QWindowKit. Библиотека QWindowKit может лучше решить проблему перемещения между несколькими экранами.

Если вы хотите полагаться на библиотеку QWindowKit, сначала необходимо скомпилировать библиотеку QWindowKit. Как подмодули проекта SARibbon, если параметр '--recursive' не включён в 'git clone', необходимо выполнить команду 'submodules update':

git submodule update --init --recursive

Компиляция в динамические библиотеки

Для получения подробной информации о процессе сборки обратитесь к документу: Building SARibbon (Сборка SARibbon).

Встраивание SARibbon непосредственно в проект

SARibbon предоставляет объединённый файл SARibbon.h и файл SARibbon.cpp, вам нужно только импортировать эти два файла в свой собственный проект и одновременно импортировать файлы ресурсов и файлы сторонних библиотек для использования, нет необходимости компилировать в динамические или статические библиотеки, вы можете обратиться к примеру StaticExample (находится в src/example/StaticExample), статическое встраивание будет использоваться для SARibbon.h, SARibbon.cpp, SARibbon.pri, SARibbonBar/resource.qrc и SARibbonBar/3rdparty, SARibbonBar/resource двух папок:

Каталог вашего проекта будет выглядеть следующим образом:

|-you-project-dir
|  |-you-project.pro
|  |-SARibbon.h
|  |-SARibbon.cpp
|  |-SARibbon.pri
|  |-SARibbonBar
|     |-resource.qrc
|     |-resource(Directly copy the resource under SARibbonBar in its entirety)
|        |-resource files

Чтобы скомпилировать с помощью qmake, вы можете выполнить следующие шаги:

1. Скопируйте SARibbon.h, SARibbon.cpp и SARibbon.pri в каталог вашего проекта.
2. Создайте папку SARibbonBar в каталоге вашего проекта.
3. Скопируйте файл src/SARibbonBar/resource.qrc в исходном коде в папку SARibbonBar каталога вашего проекта.
4. Скопируйте папку resource под src/SARibbonBar в папку

Примечание: в ответе переведён только основной текст запроса, без учёта кода и ключей в парах ключ-значение. SARibbonBar папка в директории вашего проекта

• 5. Импортируйте файл SARibbon.pri в профайл вашего проекта, например: include($$PWD/SARibbon.pri).

Если вы используете cmake, обратитесь к методу написания cmake примера StaticExample (находится в src/example/StaticExample).

Как использовать:

Импорт библиотеки

После завершения компиляции импортируйте SARibbon следующим образом:

qmake

Если вы используете qmake, вы можете просто скопировать следующие файлы в свой проект в структуру каталогов после завершения компиляции:

Сначала создайте папку 3rdparty в вашем проекте, а затем скопируйте всю папку SARibbon, внутри SARibbon уже есть несколько файлов pri, которые могут легко позволить вам импортировать проект в вашу собственную директорию, и файл ./importSARibbonBarLib.pri используется для импорта библиотеки SARibbon.

После завершения процесса апелляции вы можете добавить следующее утверждение в ваш Qt проект профайла:

include($$PWD/3rdparty/SARibbon/importSARibbonBarLib.pri)

Процесс компиляции qmake создаст папку bin_qtx.x_xx под SARibbon, и библиотечные файлы и dll файлы находятся в этой папке, и importSARibbonBarLib.pri будет автоматически ссылаться на библиотеки в этой папке.

На данный момент каталог вашего проекта выглядит так:

|-[you-project-dir]
|  |-you-project.pro
|  |-[3rdparty]
|     |-[SARibbon](Copy SARibbon in its entirety)
|        |-importSARibbonBarLib.pri
|        |-SARibbonBar.pri
|        |-common.pri
|        |-[bin_qtx.x.x_{MSVC/GNU}_x{32/64}]
|        |-[src]
|        |   |-[SARibbonBar]

cmake (рекомендуется)

Рекомендуется использовать эту библиотеку после выполнения install.

Метод введения cmake:

find_package(SARibbonBar REQUIRED)
...
target_link_libraries({your_target_name} PUBLIC SARibbonBar::SARibbonBar)

Если find_package не может найти SARibbonBar, вам необходимо сообщить вашему проекту cmake о месте установки SARibbon.

set(SARibbonBar_DIR "[your SARibbonBar installation root directory]/lib/cmake")

Если во время компиляции опция SARIBBON_INSTALL_IN_CURRENT_DIR установлена в ON (по умолчанию), папка bin_qt{Qt version}_{MSVC/GNU}_x{32/64} будет создана под корневым каталогом проекта SARibbon в качестве каталога установки. Это сделано для того, чтобы соответствовать qmake и облегчить установку нескольких различных версий Qt и компиляторов в одной операционной системе. В противном случае, в Windows, он будет установлен в папку C:\Program Files\SARibbonBar по умолчанию.

Для справки по внедрению SARibbon через cmake см. src/example/MainWindowExample/CMakeLists.txt.

Подробности см. в документации: SARibbon Building.

Быстрое начало работы

Ribbon — это сочетание строки меню и панели инструментов, отображаемое через элемент управления вкладками. Ribbon нельзя просто заменить на Tab+Toolbar, поскольку это связано с множеством деталей. SARibbon относится к стилю именования интерфейса MFC Ribbon в дизайне, страница вкладки называется Category, и под каждой Category находится несколько pannel, которая управляет кнопкой инструмента, pannel немного похожа на традиционную Toolbar, с иерархией, как показано на рисунке ниже, и эти имена ссылаются на класс интерфейса ленты MFC.

Некоторые общие существительные объясняются ниже:

• Category, представляющая то, что представляет ярлык, соответствующая SARibbonCategory.

• Context Category, это специальная категория. Она обычно не отображается. Вам нужно судить, следует ли её отображать в зависимости от контекста. Наиболее распространённый способ заключается в том, что после вставки изображения в слово появится ярлык, связанный с изменением изображения. Если изображение не выбрано, ярлык исчезнет. Это контекстная категория, соответствующая SARibbonContextCategory.

• Pannel, это набор меню, похожий на Toolbar, соответствующий SARibbonPannel.

• Application Button, это самая левая кнопка на панели вкладок (слово соответствует кнопке файла). Эта кнопка вызовет некоторые специальные действия. Страницы или меню, соответствующие SARibbonApplicationButton, можно скрыть.

• Панель быстрого доступа (Quick Access Bar) — простая панель инструментов в верхней части для размещения общих действий, соответствующих SARibbonQuickAccessBar.

• Элемент управления «Галерея» (Gallery Control) — самый привлекательный элемент управления ленты. Он отображает функции с интуитивно понятными изображениями, и даже некоторые рендеры выполняются в реальном времени в зависимости от контекста. Типичный пример — выбор стиля в офисном слове, соответствующий SARibbonGallery.

Схема расположения SARibbonBar показана на рисунке ниже.

Примечание: Различные схемы компоновки влияют на размещение категорий и панели быстрого доступа.

Использование ленты в MainWindow

Чтобы использовать SARibbon в MainWindow, необходимо заменить QMainWindow на SARibbonMainWindow, что изменяет способ отображения строки меню QMainWindow.

Обратите внимание, что если вы используете файл пользовательского интерфейса, вам следует удалить меню файла пользовательского интерфейса, иначе это может вызвать некоторые исключения.

Пример кода выглядит следующим образом:

#include "SARibbonMainWindow.h"
class MainWindow : public SARibbonMainWindow
{
    Q_OBJECT
public:
    MainWindow(QWidget* par = nullptr);
    ...
}

SARibbonMainWindow также поддерживает режим рендеринга в обычном режиме со следующим конструктором:

SARibbonMainWindow(QWidget *parent = nullptr, bool useRibbon = true);

Если второй параметр установлен в false, будет использоваться режим панели инструментов обычного меню. Этот интерфейс зарезервирован для некоторых проектов, которым необходимо иметь возможность переключаться между ленточным и классическим режимами панели инструментов меню. Лента и классический режим не поддерживают горячее переключение. Если вам нужно переключиться, вы можете установить файл конфигурации или реестр, передав значение false второму параметру при перезапуске приложения, чтобы перейти в режим классической панели инструментов меню.

Используйте SARibbonBar в QWidget или QDialog

SARibbonBar можно использовать в QWidget или QDialog, см. пример: src/example/WidgetWithRibbon.

Всё, что вам нужно сделать, это использовать SARibbonBar как обычный виджет.

Сначала объявите указатель SARibbonBar в заголовочном файле.

private:
    Ui::Widget* ui;
    SARibbonBar* mRibbonBar { nullptr };

Создайте SARibbonBar в конструкторе Widget. В файле пользовательского интерфейса виджета есть макет QVBoxLayout. Поместите SARibbonBar вверху. Поскольку используется режим QWidget, нет необходимости отображать заголовок. Вы можете вызвать метод SARibbonBar::setTitleVisible, чтобы скрыть заголовок. Можно также отменить applicationbutton в QWidget через SARibbonBar::setApplicationButton, если это не требуется. И наконец, поскольку тема SARibbonBar задаётся в методе SARibbonMainWindow, тему можно задать в QWidget с помощью глобальной функции sa_set_ribbon_theme.

Вот как это выглядит:

Создание категории и панели

Порядок создания ленты следующий: Существует специальная и очевидная кнопка под названием ApplicationButton в верхнем левом углу ленточного интерфейса. Эта кнопка обычно используется для вызова меню.

SARibbonBar создаёт ApplicationButton по умолчанию во время конструирования. Его текст можно установить следующими способами:

SARibbonBar* ribbon = ribbonBar();
ribbon->applicationButton()->setText(("File"));

По умолчанию applicationButton наследуется от SARibbonApplicationButton, а SARibbonApplicationButton наследуется от QPushButton, поэтому вы можете выполнять все операции с QPushButton. Конечно, если вы хотите установить свою собственную кнопку как applicationButton, вы можете просто вызвать функцию SARibbonBar::setApplicationButton.

QuickAccessBar и RightButtonGroup

QuickAccessBar — это панель быстрого доступа в верхнем левом углу, а RightButtonGroup — панель быстрого доступа в правом верхнем углу. В офисном режиме она разделена на левую и правую стороны. В режиме WPS левая и правая стороны будут объединены и размещены справа.

В SARibbon:

• QuickAccessBar соответствует классу SARibbonQuickAccessBar.
• RightButtonGroup соответствует классу SARibbonQuickAccessBar.

Во время инициализации SARibbonBar создаст QuickAccessBar и RightButtonGroup по умолчанию. Их указатели можно получить через SARibbonBar::quickAccessBar и SARibbonBar::rightButtonGroup. Примеры следующие:

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);
}

Стиль макета SARibbonBar

SARibbon поддерживает переключение между четырьмя стилями ленты. Здесь упоминаются стили ленты office и WPS. Переключение стилей онлайн может быть реализовано через void SARibbonBar::setRibbonStyle(RibbonStyle v).

Режим office — наиболее распространённый режим ленты, tab и строка заголовка занимают больше места, улучшен режим ленты, разработанный WPS, он уменьшает высоту ленты, метка и строка заголовка устанавливаются вместе, чтобы уменьшить высоту строки заголовка, эффективно использовать вертикальное пространство, и в то же время макет кнопок панели изменяется с максимум 3 до 2, дополнительно сжимая вертикальное пространство.

Сравнение скриншотов интерфейса Word в офисном и WPS режимах:

office	Wps

При нормальном экране стиль WPS уменьшит вертикальную высоту как минимум на 30 пикселей по сравнению со стилем Office, что эквивалентно экономии почти 3% вертикального пространства по сравнению с экраном 1920 * 1080.

В SARibbon тот, у которого есть строка заголовка, называется Loose, и элементы свободного макета расположены следующим образом:

Этот макет соответствует макету по умолчанию в Office.

В SARibbon макет со строкой заголовка и вкладкой называется компактным макетом, и элементы компактного макета расположены следующим образом. SARibbonBar предоставляет функцию setRibbonStyle, которая определяет текущий стиль макета.

Перечисление SARibbonBar::RibbonStyle определяет четыре схемы макета:

• SARibbonBar::RibbonStyleLooseThreeRow (версия v0.x — SARibbonBar::OfficeStyle);
• SARibbonBar::RibbonStyleLooseTwoRow (версия v0.x — SARibbonBar::OfficeStyleTwoRow);
• SARibbonBar::RibbonStyleCompactThreeRow (версия v0.x — SARibbonBar::WpsLiteStyle);
• SARibbonBar::RibbonStyleCompactTwoRow (версия v0.x — SARibbonBar::WpsLiteStyleTwoRow).

Обтекание текста и размер значка

Функция SARibbonBar::setEnableWordWrap позволяет контролировать, будет ли текст SARibbonBar переноситься или нет. Высота SARibbonBar фиксирована, и перенос текста или его отсутствие влияет на размер отображения значка. Если вы хотите, чтобы значок выглядел больше, вы можете установить текст без переноса.

В стиле макета SARibbonBar::RibbonStyleCompactTwoRow текст без переноса отображается следующим образом:

Текст SARibbonBar в режиме CompactTwoRow отображается так:

SARibbonBar::RibbonStyleCompactTwoRow — компактный макет, 2-строчный режим, когда текст установлен без переноса (SARibbonBar::setEnableWordWrap(false)), эффект следующий:

Когда текст SARibbonBar установлен без переноса, пространство для отображения значка становится больше.

Расположение кнопок инструментов SARibbonBar

SARibbonPannel предоставляет три метода добавления действия:

• addLargeAction;
• addMediumAction;
• addSmallAction.

В стандартном pannel действие (кнопка) имеет три режима макета. На примере офисного слова три макета панели фактически представляют собой количество занимаемых строк:

• первый, который занимает всю панель, называется «Large»;
• второй, под одной панелью можно разместить 2 кнопки, что называется «medium»;
• третий тип, панель с 3 кнопками, называется «samll».

Пример расположения кнопок в панели Word:

Для представления количества строк, которые каждая форма занимает в панели, используется SARibbonPannelItem::RowProportion. Это перечисление определяется следующим образом:

/**
 * @brief определяет пропорцию строк. Лента имеет три пропорции: large, media и small.
 */
enum RowProportion {
    None            ///< для определения пропорции она будет оцениваться в соответствии с expandingDirections. Если Qt::Vertical доступен, это равно Large, в противном случае это Small
    , Large         ///< пропорция Large, высота виджета заполнит всю панель.
    , Medium        ///< пропорция Medium будет работать только тогда, когда @ref SARibbonPannel::pannelLayoutMode равен @ref SARibbonPannel::ThreeRowMode, и займёт две из трёх строк, если обе из них в одном столбце будут Medium.
    , Small         ///< пропорция Small, в строке SARibbonPannel Medium станет Small, если не соответствует условиям, но не станет Large.
};

Каждое действие, управляемое в SARibbonPannel, будет иметь личное свойство (SARibbonPannelItem::RowProportion). Это свойство определяет расположение этого действия в панели.

Режим макета SARibbonPannel

3-строчный режим

Трёхстрочный режим — это традиционный макет панели, как показано на следующем рисунке:

В трёхстрочном режиме есть три вида заполнителей: большие, средние и маленькие.

Панель в трёхстрочном режиме будет отображать заголовок панели в области заголовка панели, а также есть ещё одна область OptionAction. Эта область используется для добавления специального триггера к этому действию. Если OptionAction не установлен, эта область скрыта.

2-строчный режим

Двухстрочный режим представляет собой улучшенный метод компоновки WPS, как показано на следующем рисунке. В двухстрочном режиме средние и маленькие заполнители (SARibbonPannelItem::RowProportion) одинаковы, и различия не делаются.

В двухстрочном режиме панель не отображает заголовок.

Настройка SARibbon

Настройка ленты — это функция ленты. Со ссылкой на пользовательский интерфейс Office и WPS пользователи могут определить множество материалов для своей собственной ленты или даже определить интерфейс, полностью отличный от исходного.

Ниже приведён пользовательский интерфейс офиса.

SARibbon относится к интерфейсу Office и WPS и инкапсулирует простой в использовании класс SARibbonCustomize, включая следующие пять классов:

• SARibbonCustomizeDialog
• SARibbonCustomizeWidget
• SARibbonCustomizeData
• SARibbonActionsManager
• SARibbonActionsManagerModel

Фактические пользователи могут использовать только SARibbonActionsManager и SARibbonCustomizeDialog/SARibbonCustomizeWidget, а другие пользователи обычно их не используют.

SARibbonActionsManager используется для управления QAction, добавляет QAction, который нужно настроить, в SARibbonActionsManager для управления и классифицирует QAction так, чтобы они могли отображаться в SARibbonCustomizeDialog/SARibbonCustomizeWidget.

SARibbonCustomizeDialog/SARibbonCustomizeWidget — это конкретное окно отображения. SARibbonCustomizeDialog инкапсулирует SARibbonCustomizeWidget как диалоговое окно. Если вы хотите интегрировать его в диалоговое окно конфигурации, такое как офис, вы можете использовать SARibbonCustomizeWidget. Эффект SARibbonCustomizeDialog показан на следующем рисунке:

Добавление пользовательских функций в интерфейс

Вот как добавить пользовательские функции.

Сначала определите SARibbonActionsManager как переменную-член MainWindow.

//Define member variables in the MainWindow.h. 
SARibbonActionsManager* m_ribbonActionMgr;///< Manage all actions

Во время инициализации MainWindow необходимо создать большое количество QAction. Родительским объектом QAction является MainWindow. Кроме того, будет сгенерирован макет ленты, такой как добавление категории, добавление панели и другие операции. После выполнения вышеуказанных операций добавьте следующие шаги, чтобы автоматически позволить SARibbonActionsManager управлять всеми QAction.

//Initialization of MainWindow and generation of QAction.
//Generate ribbon layout.
m_ribbonActionMgr = new SARibbonActionsManager(mainWinowPtr);
m_ribbonActionMgr->autoRegisteActions(mainWinowPtr);

Ключевая функция autoRegisteActions SARibbonActionsManager может проходить через все подобъекты под SARibbonMainWindow, находить и регистрировать действие, и проходить через все SARibbonCategory. Действия под SARibbonCategory классифицируются в соответствии с названием SARibbonCategory. Эта функция также регистрирует действия под SARibbonMainWindow, но не под какой-либо категорией, с тегами NotInRibbonCategoryTag, по умолчанию имя — «не в ленте».

Чтобы вызвать SARibbonCustomizeDialog, выполните следующие действия:

QString cfgpath = "customization.xml";
SARibbonCustomizeDialog dlg(this, this);

dlg.setupActionsManager(m_ribbonActionMgr);
dlg.fromXml(cfgpath);//This step is called to load the existing custom steps, which can be added based on the original custom steps when saving.
if (QDialog::Accepted == dlg.exec()) {
    dlg.applys();//Apply custom steps
    dlg.toXml(cfgpath);//Save custom steps to a file
}

Перед созданием MainWindow необходимо загрузить настраиваемый контент. Поэтому в конструктор следует добавить следующее утверждение:

//Constructor of MainWindow
sa_apply_customize_from_xml_file("customization.xml", this, m_ribbonActionMgr);

sa_apply_customize_from_xml_file — это функция, предоставляемая в SARibbonCustomizeWidget.h. Настраиваемые материалы в файле конфигурации напрямую применяются в MainWindow.