TRibbonBar

Office-style ribbon bar with tabs, groups, and buttons

Source: source/classes/tribbon.prg  |  Parent: TControl  |  Header: include/ribbon.ch

Overview

TRibbonBar implements a Microsoft Office-style ribbon interface. The ribbon docks to the top of a window and organizes commands into tabs, each containing groups of buttons. It supports multiple visual styles (2010, 2013, 2015, 2016), a Quick Access toolbar, keyboard accelerators, backstage view, and fully owner-drawn rendering with gradients.

Architecture

Component Hierarchy

TRibbonBar Properties

Key Methods

TRBGroup Methods

Groups are created by TRibbonBar:AddGroup() or the ADD GROUP command. Each group can contain buttons, separators, and other controls.

Command Syntax

#include "ribbon.ch"

// Create the ribbon bar
DEFINE RIBBONBAR [ oRBar ] ;
   [ OF oWnd ] ;
   [ PROMPTS cTab1, cTab2, cTab3 ] ;
   [ ACTION bAction ] ;
   [ OPTION nOption ] ;
   [ HEIGHT nHeight ] ;
   [ TOPMARGIN nTopMargin ] ;
   [ COLOR nClrPane ] ;
   [ COLORBOX nClrBoxOut, nClrBoxIn ] ;
   [ COLORSEL nClrBoxSelOut, nClrBoxSelIn ] ;
   [ 2010 | 2013 | 2015 | 2016 ] ;
   [ STARTBTN nStart ]

// Add a group to a tab
ADD GROUP [ oGr ] ;
   RIBBON oRBar ;
   TO nTabIndex ;
   [ PROMPT cCaption ] ;
   [ WIDTH nWidth ] ;
   [ ACTION bAction ] ;
   [ BITMAP cBitmap ]

// Add buttons to a group (using @ row, col notation)
@ nRow, nCol ADD BUTTON [ oBtn ] ;
   [ PROMPT cCaption ] ;
   [ SIZE nWidth, nHeight ] ;
   [ BITMAP cBitmap ] ;
   [ ACTION bAction ] ;
   [ OF oGroup ] ;
   [ WHEN bWhen ] ;
   [ BORDER ] ;
   [ ROUND ] ;
   [ TOP | LEFT | BOTTOM | RIGHT | CENTER ] ;
   [ NORMAL | POPUP | SPLITPOPUP | SAYBUTTON ] ;
   [ MENU oPopup ] ;
   [ TOOLTIP cToolTip ]

// Add a separator
ADD SEPARATOR TO GROUP oGr [ COL nCol ]

Ribbon Lifecycle

Code Examples

Example 1: Basic Ribbon with Groups and Buttons

#include "FiveWin.ch"
#include "Ribbon.ch"

FUNCTION Main()
   LOCAL oWnd, oRBar
   LOCAL oGrFile, oGrEdit, oGrView

   DEFINE WINDOW oWnd TITLE "Ribbon Demo"

   DEFINE RIBBONBAR oRBar OF oWnd ;
      PROMPTS "Home", "Insert", "View" ;
      HEIGHT 160 2015

   // ----- HOME TAB (option 1) -----

   ADD GROUP oGrFile RIBBON oRBar TO 1 ;
      PROMPT "File" WIDTH 140

   @ 2, 5 ADD BUTTON PROMPT "New" ;
      SIZE 36, 60 BITMAP "new32.bmp" ;
      ACTION NewDocument() ;
      OF oGrFile TOP

   @ 2, 45 ADD BUTTON PROMPT "Open" ;
      SIZE 36, 60 BITMAP "open32.bmp" ;
      ACTION OpenDocument() ;
      OF oGrFile TOP

   @ 2, 85 ADD BUTTON PROMPT "Save" ;
      SIZE 36, 60 BITMAP "save32.bmp" ;
      ACTION SaveDocument() ;
      OF oGrFile TOP

   ADD GROUP oGrEdit RIBBON oRBar TO 1 ;
      PROMPT "Editing" WIDTH 180

   @ 2, 5 ADD BUTTON PROMPT "Cut" ;
      SIZE 50, 22 BITMAP "cut16.bmp" ;
      ACTION Cut() OF oGrEdit

   @ 26, 5 ADD BUTTON PROMPT "Copy" ;
      SIZE 50, 22 BITMAP "copy16.bmp" ;
      ACTION Copy() OF oGrEdit

   @ 50, 5 ADD BUTTON PROMPT "Paste" ;
      SIZE 50, 22 BITMAP "paste16.bmp" ;
      ACTION Paste() OF oGrEdit

   ADD SEPARATOR TO GROUP oGrEdit COL 65

   @ 2, 70 ADD BUTTON PROMPT "Find" ;
      SIZE 50, 22 BITMAP "find16.bmp" ;
      ACTION FindText() OF oGrEdit

   @ 26, 70 ADD BUTTON PROMPT "Replace" ;
      SIZE 60, 22 BITMAP "replace16.bmp" ;
      ACTION ReplaceText() OF oGrEdit

   // ----- INSERT TAB (option 2) -----

   ADD GROUP oGrView RIBBON oRBar TO 2 ;
      PROMPT "Objects" WIDTH 200

   @ 2, 5 ADD BUTTON PROMPT "Table" ;
      SIZE 36, 60 BITMAP "table32.bmp" ;
      ACTION InsertTable() OF oGrView TOP

   @ 2, 50 ADD BUTTON PROMPT "Image" ;
      SIZE 36, 60 BITMAP "image32.bmp" ;
      ACTION InsertImage() OF oGrView TOP

   @ 2, 95 ADD BUTTON PROMPT "Chart" ;
      SIZE 36, 60 BITMAP "chart32.bmp" ;
      ACTION InsertChart() OF oGrView TOP

   SET MESSAGE OF oWnd TO "Ready" CENTERED

   ACTIVATE WINDOW oWnd
RETURN NIL

Example 2: Ribbon with Quick Access and Backstage

#include "FiveWin.ch"
#include "Ribbon.ch"

FUNCTION RibbonAdvanced()
   LOCAL oWnd, oRBar, oBackStage

   DEFINE WINDOW oWnd TITLE "Advanced Ribbon"

   DEFINE RIBBONBAR oRBar OF oWnd ;
      PROMPTS "Home", "Data", "Reports" ;
      HEIGHT 160 2016 ;
      STARTBTN 1

   // Quick Access round button (File orb)
   oRBar:QuickRoundBtn( "orb.bmp",, , , ;
      { || oRBar:BackStage() } )

   // Backstage panel (shown when orb is clicked)
   oBackStage := TPanel():New( 0, 0, 600, 300, oWnd )
   @ 2, 2 SAY "New"   OF oBackStage
   @ 4, 2 SAY "Open"  OF oBackStage
   @ 6, 2 SAY "Save"  OF oBackStage
   @ 8, 2 SAY "Print" OF oBackStage
   oBackStage:Hide()
   oRBar:SetBackStage( oBackStage )

   // Tab change handling
   oRBar:bAction := { |nTab, nOld| ;
      MsgInfo( "Switched from tab " + Str(nOld) + ;
               " to tab " + Str(nTab) ) }

   // Disable a tab at runtime
   // oRBar:Enable( 3, .F. )

   // Hide a tab at runtime
   // oRBar:Hide( 2 )

   ACTIVATE WINDOW oWnd
RETURN NIL

Example 3: Popup Buttons and Split Buttons

// Button with a dropdown popup menu
LOCAL oPopup

MENU oPopup POPUP
   MENUITEM "Option A" ACTION DoA()
   MENUITEM "Option B" ACTION DoB()
   SEPARATOR
   MENUITEM "More..."  ACTION DoMore()
ENDMENU

@ 2, 5 ADD BUTTON PROMPT "Dropdown" ;
   SIZE 80, 60 BITMAP "menu32.bmp" ;
   ACTION NIL ;
   OF oGroup ;
   POPUP ;
   MENU oPopup TOP

// Split button: click fires action, arrow opens menu
@ 2, 90 ADD BUTTON PROMPT "Print" ;
   SIZE 70, 60 BITMAP "print32.bmp" ;
   ACTION QuickPrint() ;
   OF oGroup ;
   SPLITPOPUP ;
   MENU oPopup TOP

Visual Styles

You can change the style at runtime using SetStyles():

// Switch to 2016 style
oRBar:SetStyles( .F., .F., .F., 25, , , , , , , , , , .T. )

Tips

• Always include ribbon.ch for the ribbon command preprocessor directives.
• The ribbon height should be around 140-160 pixels for comfortable button placement.
• Use TOP layout for large icon buttons (icon above text) and default layout for small icon buttons (icon left of text).
• Groups are added to specific tabs via the TO nOption clause. Tab indices are 1-based.
• Use SPLITPOPUP type for buttons that have both a direct action and a dropdown menu.
• Keyboard accelerators are automatically supported when lUseAcc is .T. -- press Alt to show key hints.
• The WHEN clause on buttons supports dynamic enable/disable based on application state.
• For responsive layouts, the ribbon automatically resizes with the window width.

See Also

• TControl -- parent class
• TButton / TBtnBmp -- traditional toolbar buttons
• TMenu -- menus used in popup/split buttons
• More Controls -- TReBar for classic dockable toolbars