SARibbon

repository·master·Indexed 23 days ago

https://github.com/czyt1988/saribbon

A Qt Ribbon UI framework for creating ribbon-style user interfaces in Qt applications. It includes PyQtSARibbon (version 2.8.0) for PyQt5 bindings. The library provides core classes such as SARibbonMainWindow, SARibbonBar, SARibbonCategory, and SARibbonPanel to implement ribbon bars, quick access toolbars, contextual categories, and gallery widgets. It supports custom styling via QSS, action persistence, RTL support, and integration with QMdiArea and Qt Designer .ui files.

Tokens
71K
Snippets
134
Records
296
Agent score
78%

What's inside SARibbon

  1. Overview of SARibbon

    master

    SARibbon is a Qt-based Ribbon interface control library designed to provide modern desktop application interfaces similar to the Microsoft Office series. It is suitable for large-scale, industrial-grade, and complex desktop applications.

    Key design principles include:

    • Interface naming conventions inspired by MFC Ribbon.
    • Visual styles that blend the strengths of Microsoft Office and WPS Office.
    • Support for rapid theme customization via QSS (Qt Style Sheets).
    • Rich set of built-in encapsulated controls (e.g., color pickers).
  2. Overview of SARibbon UI Library

    master

    SARibbon is a Qt-based Ribbon UI control library designed to create modern, Microsoft Office-style interfaces for desktop applications. It is suitable for large-scale, industrial-grade, or complex software.

    Key characteristics include:

    • API Style: Naming conventions are inspired by MFC Ribbon.
    • UI Style: A hybrid of Microsoft Office and WPS Office aesthetics.
    • Customization: Supports rapid theme changes using QSS (Qt Style Sheets).
    • Compatibility: Works with Qt 5.14+ and Qt 6, supporting Windows, Ubuntu, and macOS.
  3. Understand the MatlabUI architecture and key classes

    master

    The MatlabUI example demonstrates a streamlined ribbon interface mimicking MATLAB. It uses a custom QSS stylesheet (theme-matlab.qss) to achieve a specific look (deep blue ribbon bar, white tab backgrounds) rather than using the built-in SARibbon themes.

    Key components used in this example include:

    • MainWindow: Inherits from SARibbonMainWindow to provide a minimal ribbon setup.
    • SARibbonBar: The main ribbon bar, configured via custom QSS.
    • SARibbonCategory: Tab pages that host panels containing ribbon controls.
    • SARibbonQuickAccessBar: A minimal toolbar for quick access commands.
    • SARibbonApplicationWidget: The application menu widget located at the top-left.
    • SARibbonPanel: Used to group controls within a category.
  4. Understand SARibbon build artifacts

    master

    After running the installation step, SARibbon products are organized into a directory named bin_qt{version}_{compiler}_x{arch}/.

    Example structure:

    bin_qt6.7.3_MSVC_x64/
    ├── bin/                  # Executables and DLLs (e.g., SARibbon.dll, example apps)
    ├── lib/                  # Import libraries (.lib files)
    ├── include/              # Header files
    └── share/                # CMake configuration files
  5. Key classes in the uiform integration pattern

    master

    The following classes are central to the pattern of integrating SARibbon with Qt Designer files:

    • MainWindow: A class inheriting from SARibbonMainWindow that utilizes a generated Ui::MainWindow class from a .ui file.
    • SARibbonBar: The main ribbon component, created programmatically to replace the designer-defined menubar.
    • SARibbonPanel: A container within the ribbon bar that hosts actions, including QAction instances defined in the .ui file.
    • Ui::MainWindow: The auto-generated class produced by the Qt UI compiler (uic) from MainWindow.ui.
  6. Understand the SARibbon button layout architecture

    master

    Since v2.7.0, SARibbonToolButton uses a Strategy Pattern to handle layout calculations. This separates the logic for different button sizes and styles into a hierarchy of strategy classes.

    Key components:

    • SARibbonButtonLayoutStrategy: The abstract base class for all layout logic.
    • SARibbonLargeButtonLayoutStrategy & SARibbonSmallButtonLayoutStrategy: Concrete implementations for different button sizes.
    • SARibbonButtonLayoutContext: A data object containing all parameters required for a layout calculation, such as buttonSize, iconSize, spacing, wordWrap, hasMenu, text, and fontMetrics.

    This architecture allows for easy extension of new button types and better testing of layout logic.

  7. Configure Ribbon Layout Styles and Row Proportions

    master

    SARibbon panels use a grid layout where actions occupy different 'placeholder sizes'. The visual effect depends on the SARibbonBar layout style set via setRibbonStyle.

    Placeholder Sizes:

    • Large Action: Occupies 2 or 3 rows in height (depending on mode). Displays large icon + text.
    • Medium Action: Occupies 1 or 1.5 rows. Displays icon + text.
    • Small Action: Occupies 1 row.

    Layout Modes:

    • 3-row mode: Standard ribbon layout with three vertical rows.
    • 2-row mode: Standard ribbon layout with two vertical rows. In this mode, Medium and Small placeholders are treated identically.
    • Single-row mode (v2.8.0+): All buttons are in one horizontal row (icon left, text right). All placeholders (Large, Medium, Small) behave as Small. For best results, call SARibbonBar::setEnableIconRightText(true).
  8. Configure Menu Button Popup Modes

    master

    SARibbon allows you to add menus to panels using different QToolButton::ToolButtonPopupMode styles. This determines how the user interacts with the button and its associated menu.

    Available Popup Modes:

    1. QToolButton::DelayedPopup: Clicking the button executes the default action. Pressing and holding the button pops up the menu. Best for buttons where the primary action is common and the menu provides advanced options.
    2. QToolButton::MenuButtonPopup: (Recommended for Office-style UIs) The button is split into two parts. Clicking the icon executes the default action; clicking the text/arrow pops up the menu. This clearly distinguishes primary and secondary operations.
    3. QToolButton::InstantPopup: Clicking any part of the button immediately pops up the menu without executing a default action. Best for buttons where the function is defined entirely by the menu options.

    Implementation Methods:

    • Via QAction: Use addLargeAction(QAction* action, ToolButtonPopupMode popMode), etc. The QAction must have the menu attached via action->setMenu(QMenu*) beforehand.
    • Directly via SARibbonPanel: Use addMenu(QMenu* menu, ...) or addLargeMenu, addMediumMenu, addSmallMenu. These methods use the menu's own internal action, so you don't need to create a separate QAction object. Warning: These methods may modify properties of menu->menuAction(); set custom icons/text before calling them.
  9. Important considerations for Color Widgets

    master

    When working with color widgets in SARibbon, keep the following in mind:

    • Ribbon vs. General UI: Use SARibbonColorToolButton for Ribbon-based applications and SAColorToolButton for any other standard Qt interface.
    • Icon Replacement: In SARibbonColorToolButton::ColorFillToIcon mode, calling setIcon() has no effect because setColor() automatically replaces the icon with a color icon.
    • Menu Creation: For ease of use, prefer SARibbonColorToolButton::setupStandardColorMenu() or SAColorToolButton::createColorMenu() instead of manually assembling an SAColorMenu.
    • Standard Colors: Use SA::getStandardColorList() to access the 10 predefined standard colors (red, orange, yellow, green, cyan, blue, purple, magenta, black, white).
    • No-Color/Clearing Colors: To allow users to clear a color, call SAColorMenu::enableNoneColorAction(true). This allows selecting QColor() (an invalid color). Use QColor::isValid() to check for this state during custom painting.
    • Custom Color Limits: SAColorMenu tracks up to 10 custom colors. If a user adds more, the oldest custom color is automatically removed.
  10. Use SARibbonContextCategory for conditional tabs

    master

    A SARibbonContextCategory is a special category manager used to show or hide groups of tabs based on application state (e.g., showing "Picture Tools" only when an image is selected).

    Contextual categories are hidden by default. You must control their visibility programmatically using showContextCategory() or hideContextCategory() on the SARibbonBar.

  11. Visualize concepts with Mermaid diagrams

    master

    For complex concepts, use mermaid syntax to provide visual aids. This is preferred over static images for class relationships and workflows.

    Mermaid Class Diagrams

    Use for class inheritance and composition:

    classDiagram
        class DAAbstractNode {
            +execute() bool
            +getNodeName() QString
        }
        class DAWorkflowNode {
            -m_workflow: DAWorkflow*
            +setWorkflow(workflow)
            +execute() bool
        }
        DAAbstractNode <|-- DAWorkflowNode

    Mermaid Flowcharts

    Use for usage flows and workflows:

    flowchart TD
        A[Create workflow] --> B[Add nodes]
        B --> C[Connect nodes]
        C --> D[Configure parameters]
        D --> E[Execute workflow]
        E --> F[View results]

    Mermaid Sequence Diagrams

    Use for inter-module interactions and signal-slot connections:

    sequenceDiagram
        participant User
        participant WorkflowScene
        participant NodeItem
        participant LinkItem
        
        User->>WorkflowScene: Drag in node
        WorkflowScene->>NodeItem: Create node
        User->>NodeItem: Drag connection
        NodeItem->>LinkItem: Create connection
        LinkItem->>WorkflowScene: Connection complete signal
    classDiagram
        class DAAbstractNode {
            +execute() bool
            +getNodeName() QString
        }
        class DAWorkflowNode {
            -m_workflow: DAWorkflow*
            +setWorkflow(workflow)
            +execute() bool
        }
        
        DAAbstractNode <|-- DAWorkflowNode
  12. Enable native window features via QWindowKit

    master

    SARibbon includes a simple built-in borderless mode, but for advanced native OS window features (such as Windows 7+ snap-to-edge handling, Windows 11 Snap Layout effects, or improved multi-monitor movement), you should use the QWindowKit library.

    To use it, you must first compile QWindowKit as a third-party dependency. If you cloned the repository without the --recursive flag, ensure you initialize the submodules first:

    git submodule update --init --recursive