The UI ribbon is a horizontal menu bar typically located at the top of the application interface or along the side. More...

Inheritance diagram for Ribbon:

[legend]

Collaboration diagram for Ribbon:

[legend]

Public Member Functions
	Ribbon (QWidget *parent=nullptr)
	Constructs a ribbon widget.
void	addBottomRightWidget (QWidget *widget)
	Adds a widget to the bottom-right area of the ribbon (after the groups).
virtual RibbonGroup *	addGroup (const TranslatedString &label)
	Adds a new ribbon group with the given label, creating it if necessary.
virtual void	addGroup (RibbonGroup *group)
	Adds an existing ribbon group to the ribbon.
virtual RibbonGroup *	addGroup (uint04 index, const TranslatedString &label)
	Adds a new ribbon group at a specific index with the given label.
virtual void	addGroup (uint04 index, RibbonGroup *group)
	Adds an existing ribbon group at a specific index.
void	addTopLeftWidget (QWidget *widget)
	Adds a widget to the top-left area of the ribbon (before the groups).
void	cleanupEmpty ()
	Removes any empty ribbon groups.
RibbonGroup &	group (const TranslatedString &group_name)
	Returns a mutable reference to the ribbon group with the given name.
const RibbonGroup &	group (const TranslatedString &group_name) const
	Returns a const reference to the ribbon group with the given name.
RibbonGroup &	group (uint04 index)
	Returns a mutable reference to the ribbon group at the given index.
DockWidget< RibbonGroup > *	groupDock (const RibbonGroup *group)
	Returns the dock widget wrapping the given ribbon group.
DockWidget< RibbonGroup > *	groupDock (const TranslatedString &group_name)
	Returns the dock widget for the ribbon group with the given name.
DockWidget< RibbonGroup > *	groupDock (uint04 index)
	Returns the dock widget for the ribbon group at the given index.
Dictionary< TranslatedString, DockWidget< RibbonGroup > * > &	groups ()
	Returns a reference to the dictionary of all ribbon groups keyed by name.
virtual bool	hasGroup (const TranslatedString &group) const
	Checks whether a ribbon group with the given name exists.
bool	isVertical ()
	Returns whether the ribbon is oriented vertically.
QSize	minimumSizeHint () const override
	Returns the minimum recommended size for the ribbon.
RibbonGroup &	operator[] (const TranslatedString &location)
	Returns the ribbon group with the given name, creating it if it does not exist.
virtual void	removeAllGroups ()
	Removes all ribbon groups from the ribbon.
virtual void	removeGroup (const TranslatedString &label)
	Removes the ribbon group with the given label.
virtual void	removeGroup (RibbonGroup *group)
	Removes a specific ribbon group.
virtual void	removeGroup (uint04 index)
	Removes the ribbon group at the given index.
SectionWidget *	section () const
	Returns the parent section widget that contains this ribbon.
void	setFixedNumOfRows (uint01 fixed_num_of_rows)
	Sets a fixed number of rows for the ribbon layout.
void	setGroupName (uint04 index, const TranslatedString &group_name)
	Renames the ribbon group at the given index.
void	setInverseRibbonArea (bool inverse_ribbon_area)
	Sets whether the ribbon area orientation should be inverted.
void	setLayoutMode (RibbonLayoutMode mode)
	Sets the layout mode for how ribbon groups are arranged.
void	setTabLock (bool tab_lock)
	Sets whether tabs are locked (preventing the user from switching tabs).
QSize	sizeHint () const override
	Returns the recommended size for the ribbon.
void	slideInIdx (uint04 idx, enum StackAnimationDirection direction=StackAnimationDirection::e_automatic) override
	Slides to the ribbon page at the given index with an optional animation direction.
void	updateRibbonLayout ()
	Recalculates and updates the layout of all ribbon groups.
Public Member Functions inherited from ContainerWidgetBase
	ContainerWidgetBase (QWidget *parent=nullptr)
	Constructs a ContainerWidgetBase with the given parent widget.
Public Member Functions inherited from QCustomStackedWidgetBase
void	animationFinished ()
	Signal emitted when a slide animation completes.
QSize	minimumSizeHint () const override
	Returns the minimum recommended size for the stacked widget.
void	setAnimation (enum QEasingCurve::Type animationtype)
	Sets the easing curve type used for slide animations.
virtual void	setCurrentIdx (uint04 current_index)
	Sets the current visible page index without animation.
void	setCustomPixmap (QPixmap *pixmap)
	Sets a custom pixmap to render during slide transitions instead of widget captures.
void	setSpeed (int speed)
	Sets the animation duration in milliseconds for slide transitions.
void	setVerticalMode (bool vertical=true)
	Enables or disables vertical slide animation mode.
void	setWrap (bool wrap)
	Sets whether page navigation wraps around from last to first and vice versa.
QSize	sizeHint () const override
	Returns the recommended size for the stacked widget.

Private Member Functions
virtual void	_setVertical (bool is_vertical)
	Sets the ribbon orientation to vertical or horizontal.

Additional Inherited Members
Public Types inherited from QCustomStackedWidgetBase
enum	StackAnimationDirection { e_left_to_right , e_right_to_left , e_top_to_bottom , e_bottom_to_top , e_automatic }
	Defines the direction of slide animations between stacked pages. More...
Static Public Attributes inherited from QCustomStackedWidgetBase
static ApplicationOption< sint04 >	default_stack_animation_speed
	Default time in milliseconds to animate a slide transition.
Protected Member Functions inherited from ContainerWidgetBase
virtual FloatingWidget *	addSectionContent (SectionContent *sc)
	Adds section content as a new floating widget.
virtual SectionWidget *	addSectionContent (SectionContent sc, SectionWidget sw, DropArea area=e_drop_center)
	Adds section content to an existing section widget in the specified drop area.
void	beginResetAll ()
	Begins a reset-all operation, saving current state for later restoration.
void	bringFloatingWidgetsForward ()
	Brings all floating widgets owned by this container to the front of the window stack.
virtual void	clearAllNonFloatingContent ()
	Removes all non-floating section content from this container.
virtual void	clearAllSectionContent ()
	Removes all section content from this container, including floating widgets.
Buffer< SectionContent * >	contents () const
	Returns all section contents managed by this container.
DropOverlay *	dropOverlay ()
	Returns the drop overlay used for drag-and-drop visual feedback.
void	endResetAll ()
	Ends a reset-all operation, restoring layout to the saved state.
bool	event (QEvent *event) override
	Handles events for this widget, including custom event processing.
bool	hasSectionContent (SectionContent *sc)
	Checks whether the given section content exists within this container.
bool	hideSectionContent (SectionContent *sc, PopupInfo end=PopupInfo())
	Hides the given section content, optionally with popup animation.
bool	isSectionContentVisible (SectionContent *sc)
	Checks whether the given section content is currently visible.
FloatingWidget *	makeFloating (SectionContent *sc, bool show, PopupInfo start=PopupInfo(), PopupInfo end=PopupInfo())
	Makes the given section content into a floating widget.
FloatingWidget *	makeFullScreen (SectionContent *sc, PopupInfo start=PopupInfo())
	Makes the given section content fullscreen.
QSize	minimumSizeHint () const override
	Returns the minimum recommended size for this widget.
QRect	outerBottomDropRect () const
	Returns the drop rectangle for the outer bottom area of this container.
QRect	outerLeftDropRect () const
	Returns the drop rectangle for the outer left area of this container.
QRect	outerRightDropRect () const
	Returns the drop rectangle for the outer right area of this container.
QRect	outerTopDropRect () const
	Returns the drop rectangle for the outer top area of this container.
bool	popWindowStack ()
	Pops the top item from the fullscreen window stack, restoring the previous state.
bool	raiseSectionContent (SectionContent *sc)
	Raises the given section content to the front of its section widget.
void	removeFromResetShow (UUID id)
	Removes the given section ID from the list of sections to be shown during reset restoration.
bool	removeSectionContent (SectionContent *sc)
	Removes the given section content from this container.
void	resizeEvent (QResizeEvent *event) override
	Handles resize events to update internal layout geometry.
virtual void	setShouldAnimateAdd (bool animate)
	Sets whether adding new section content should be animated.
void	setTabLock (bool tab_lock)
	Locks or unlocks tab movement for all section widgets in this container.
bool	showSectionContent (SectionContent *sc, PopupInfo start=PopupInfo(), PopupInfo end=PopupInfo())
	Shows the given section content, optionally with popup animation.
QSize	sizeHint () const override
	Returns the recommended size for this widget.
void	swapSectionContent (SectionContent section_a, SectionContent section_b)
	Swaps the positions of two section contents within the container.
Protected Member Functions inherited from QCustomStackedWidgetBase
	QCustomStackedWidgetBase (QWidget *parent=nullptr)
	Constructs the stacked widget base.
uint04	activeIndex () const
	Returns the index of the currently active (or animating-to) widget.
QWidget *	activeWidget () const
	Returns the currently active (or animating-to) widget.
virtual uint04	addWidget (QWidget *w)
	Adds a widget as a new page in the stacked widget.
void	animationDoneSlot ()
	Slot called when the slide animation completes to finalize the transition.
double	animationPercent () const
	Returns the current animation interpolation percent.
void	childDestroyedSlot (QObject *widget)
	Slot called when a child widget is destroyed, to remove it from the page list.
uint04	count () const
	Returns the number of pages in the stacked widget.
uint04	currentIndex () const
	Returns the index of the currently displayed page.
QWidget *	currentWidget () const
	Returns the currently displayed widget.
bool	eventFilter (QObject object, QEvent event) override
	Filters events for child widgets to handle layout and visibility changes.
uint04	indexOf (QWidget *widget) const
	Returns the index of the given widget in the stacked widget.
void	insertWidget (uint04 index, QWidget *w)
	Inserts a widget at a specific index in the stacked widget.
virtual void	moveContent (uint04 from, uint04 to)
	Moves a child widget from one index to another.
void	paintEvent (QPaintEvent *) override
	Custom paint event that renders slide transition animations.
void	removeWidget (QWidget *widget)
	Removes a widget from the stacked widget.
void	removeWidget (QWidget widget, QWidget slide_to_if_active)
	Removes a widget and slides to a replacement widget if it was the active page.
void	resizeEvent (QResizeEvent *event) override
	Handles resize events to update child widget geometries.
void	setAnimationPercent (double animation_percent)
	Sets the current animation interpolation percent for the Q_PROPERTY system.
void	showEvent (QShowEvent *event) override
	Handles show events to ensure proper layout of the active widget.
virtual void	slideInAnimation (enum StackAnimationDirection direction=e_automatic, bool cache_in_image=false)
	Executes the slide animation between the current and next pages.
virtual void	slideInAnimation (PopupInfo origin_rect, enum StackAnimationDirection direction=e_automatic, bool cache_in_image=false)
	Executes the slide animation using popup origin information.
virtual void	slideInIdx (uint04 idx, int delay_time=0, enum StackAnimationDirection direction=e_automatic)
	Slides to the page at the given index with animation.
virtual void	slideInIdx (uint04 idx, PopupInfo origin_rect, int delay_time=0, enum StackAnimationDirection direction=e_automatic)
	Slides to the page at the given index with animation and popup origin info.
virtual void	slideInNext ()
	Slides to the next page with animation.
virtual void	slideInPrev ()
	Slides to the previous page with animation.
virtual void	slideInWgt (QWidget *widget, enum StackAnimationDirection direction=e_automatic, bool force_slide=false)
	Slides to a specific widget with animation.
virtual void	swapIndices (uint04 a, uint04 b)
	Swaps two child widgets at the given indices.
QWidget *	widget (uint04 index) const
	Returns the widget at the given index.
Protected Attributes inherited from ContainerWidgetBase
bool	m_animate_add = true
	Whether to animate the addition of new section content.
DropOverlay *	m_drop_overlay
	The overlay shown during drag-and-drop operations.
Buffer< std::pair< QPointer< QWidget >, Buffer< QPointer< FloatingWidget > > > >	m_fullscreen_stack
	Stack of fullscreen states for navigating back.
Buffer< std::pair< QPointer< QWidget >, Buffer< QPointer< FloatingWidget > > > >	m_reset_fullscreen_stack
	Saved fullscreen stack for reset restoration.
bool	m_reset_is_on_home = false
	Whether the reset state corresponds to the home layout.
Buffer< UUID >	m_reset_visible_sections
	UUIDs of sections that should be visible after a reset.
Dictionary< UUID, SectionContent * >	m_section_content
	Maps section content UUIDs to their SectionContent pointers.
Dictionary< UUID, SectionWidget * >	m_sections
	Maps section UUIDs to their SectionWidget pointers.
Buffer< SharedSectionContentArea * >	m_shared_content
	All shared content area splitters in this container.
SectionWidget *	m_top_section_widget = nullptr
	The top-level section widget, if any.
SharedSectionContentArea *	m_top_splitter = nullptr
	The top-level splitter managing the layout of all sections.
Protected Attributes inherited from QCustomStackedWidgetBase
double	m_animation_percent
	The current animation interpolation percent (0.0 to 1.0).
enum QEasingCurve::Type	m_animationtype
	The easing curve type for slide animations.
Buffer< QWidget * >	m_child_widgets
	The list of child page widgets.
uint04	m_current_index
	The index of the currently displayed page.
bool	m_is_animating
	Whether a slide animation is currently in progress.
uint04	m_last
	The index of the previously displayed page.
int	m_last_animation_time
	The duration of the last animation in milliseconds.
QPointer< QPropertyAnimation >	m_move_animation
	The property animation driving slide transitions.
uint04	m_next
	The index of the page being animated to.
uint04	m_now
	The index of the currently displayed page during animation.
QPoint	m_offset
	The pixel offset used during slide animation rendering.
PopupInfo	m_popup_info
	The popup info used for animation origin calculations.
int	m_speed
	The animation duration in milliseconds.
bool	m_vertical
	Whether slide animations are in vertical mode.
bool	m_wrap = false
	Whether page navigation wraps around at boundaries.

Detailed Description

The UI ribbon is a horizontal menu bar typically located at the top of the application interface or along the side.

It organizes commands and tools into tabs and groups for easy access. Each tab contains related functionality, categorized into sections such as File, Edit, View, etc. Within these sections, buttons, dropdowns, and other controls allow users to interact with the application features efficiently. The ribbon improves usability by presenting frequently-used commands in a visually organized manner.

See also: RibbonGroup, RibbonSubGroup, ContainerWidget

Definition at line 55 of file Ribbon.h.

Constructor & Destructor Documentation

◆ Ribbon()

Ribbon::Ribbon ( QWidget * parent = nullptr )

explicit

Constructs a ribbon widget.

Parameters

[in] parent Optional parent widget.

References Ribbon().

Referenced by Ribbon().

Member Function Documentation

◆ _setVertical()

virtual void Ribbon::_setVertical ( bool is_vertical )

privatevirtual

Sets the ribbon orientation to vertical or horizontal.

Parameters

[in] is_vertical True for vertical orientation.

◆ addBottomRightWidget()

void Ribbon::addBottomRightWidget ( QWidget * widget )

Adds a widget to the bottom-right area of the ribbon (after the groups).

Parameters

[in] widget The widget to add.

References QCustomStackedWidgetBase::widget().

◆ addGroup() [1/4]

virtual RibbonGroup * Ribbon::addGroup ( const TranslatedString & label )

virtual

Adds a new ribbon group with the given label, creating it if necessary.

Parameters

[in] label The translated label for the new group.

Returns: Pointer to the created RibbonGroup.

Referenced by operator[]().

◆ addGroup() [2/4]

virtual void Ribbon::addGroup ( RibbonGroup * group )

virtual

Adds an existing ribbon group to the ribbon.

Parameters

[in] group The ribbon group to add.

References group().

◆ addGroup() [3/4]

virtual RibbonGroup * Ribbon::addGroup	(	uint04	index,
		const TranslatedString &	label )

virtual

Adds a new ribbon group at a specific index with the given label.

Parameters

[in]	index	The insertion index.
[in]	label	The translated label for the new group.

Returns: Pointer to the created RibbonGroup.

◆ addGroup() [4/4]

virtual void Ribbon::addGroup	(	uint04	index,
		RibbonGroup *	group )

virtual

Adds an existing ribbon group at a specific index.

Parameters

[in]	index	The insertion index.
[in]	group	The ribbon group to add.

References group().

◆ addTopLeftWidget()

void Ribbon::addTopLeftWidget ( QWidget * widget )

Adds a widget to the top-left area of the ribbon (before the groups).

Parameters

[in] widget The widget to add.

References QCustomStackedWidgetBase::widget().

◆ group() [1/3]

RibbonGroup & Ribbon::group ( const TranslatedString & group_name )

Returns a mutable reference to the ribbon group with the given name.

Parameters

[in] group_name The translated name of the group.

Returns: A reference to the matching RibbonGroup.

◆ group() [2/3]

const RibbonGroup & Ribbon::group ( const TranslatedString & group_name ) const

Returns a const reference to the ribbon group with the given name.

Parameters

[in] group_name The translated name of the group.

Returns: A const reference to the matching RibbonGroup.

Referenced by addGroup(), addGroup(), groupDock(), hasGroup(), operator[](), and removeGroup().

◆ group() [3/3]

RibbonGroup & Ribbon::group ( uint04 index )

Returns a mutable reference to the ribbon group at the given index.

Parameters

[in] index The group index.

Returns: A reference to the RibbonGroup.

◆ groupDock() [1/3]

DockWidget< RibbonGroup > * Ribbon::groupDock ( const RibbonGroup * group )

Returns the dock widget wrapping the given ribbon group.

Parameters

[in] group The ribbon group to look up.

Returns: Pointer to the dock widget, or nullptr if not found.

References group().

◆ groupDock() [2/3]

DockWidget< RibbonGroup > * Ribbon::groupDock ( const TranslatedString & group_name )

inline

Returns the dock widget for the ribbon group with the given name.

Parameters

[in] group_name The translated name of the group.

Returns: Pointer to the dock widget.

Definition at line 107 of file Ribbon.h.

◆ groupDock() [3/3]

DockWidget< RibbonGroup > * Ribbon::groupDock ( uint04 index )

inline

Returns the dock widget for the ribbon group at the given index.

Parameters

[in] index The group index.

Returns: Pointer to the dock widget.

Definition at line 122 of file Ribbon.h.

◆ groups()

Dictionary< TranslatedString, DockWidget< RibbonGroup > * > & Ribbon::groups ( )

inline

Returns a reference to the dictionary of all ribbon groups keyed by name.

Returns: The group dictionary.

Definition at line 220 of file Ribbon.h.

◆ hasGroup()

virtual bool Ribbon::hasGroup ( const TranslatedString & group ) const

virtual

Checks whether a ribbon group with the given name exists.

Parameters

[in] group The translated name to look up.

Returns: True if the group exists.

References group().

Referenced by operator[]().

◆ isVertical()

bool Ribbon::isVertical ( )

inline

Returns whether the ribbon is oriented vertically.

Returns: True if the ribbon layout is vertical.

Definition at line 68 of file Ribbon.h.

◆ minimumSizeHint()

QSize Ribbon::minimumSizeHint ( ) const

override

Returns the minimum recommended size for the ribbon.

Returns: The minimum size hint.

◆ operator[]()

RibbonGroup & Ribbon::operator[] ( const TranslatedString & location )

inline

Returns the ribbon group with the given name, creating it if it does not exist.

Parameters

[in] location The translated group name.

Returns: A reference to the RibbonGroup.

Definition at line 189 of file Ribbon.h.

References addGroup(), group(), and hasGroup().

◆ removeGroup() [1/3]

virtual void Ribbon::removeGroup ( const TranslatedString & label )

virtual

Removes the ribbon group with the given label.

Parameters

[in] label The translated label of the group to remove.

◆ removeGroup() [2/3]

virtual void Ribbon::removeGroup ( RibbonGroup * group )

virtual

Removes a specific ribbon group.

Parameters

[in] group The ribbon group to remove.

References group().

◆ removeGroup() [3/3]

virtual void Ribbon::removeGroup ( uint04 index )

virtual

Removes the ribbon group at the given index.

Parameters

[in] index The index of the group to remove.

◆ section()

SectionWidget * Ribbon::section ( ) const

Returns the parent section widget that contains this ribbon.

Returns: Pointer to the SectionWidget.

◆ setFixedNumOfRows()

void Ribbon::setFixedNumOfRows ( uint01 fixed_num_of_rows )

Sets a fixed number of rows for the ribbon layout.

Parameters

[in] fixed_num_of_rows The number of rows, or 0 for automatic.

◆ setGroupName()

void Ribbon::setGroupName	(	uint04	index,
		const TranslatedString &	group_name )

Renames the ribbon group at the given index.

Parameters

[in]	index	The group index.
[in]	group_name	The new translated name.

◆ setInverseRibbonArea()

void Ribbon::setInverseRibbonArea ( bool inverse_ribbon_area )

Sets whether the ribbon area orientation should be inverted.

Parameters

[in] inverse_ribbon_area True to invert the ribbon area.

◆ setLayoutMode()

void Ribbon::setLayoutMode ( RibbonLayoutMode mode )

Sets the layout mode for how ribbon groups are arranged.

Parameters

[in] mode The ribbon layout mode.

◆ setTabLock()

void Ribbon::setTabLock ( bool tab_lock )

inline

Sets whether tabs are locked (preventing the user from switching tabs).

Parameters

[in] tab_lock True to lock tabs.

Definition at line 243 of file Ribbon.h.

References ContainerWidgetBase::setTabLock().

◆ sizeHint()

QSize Ribbon::sizeHint ( ) const

override

Returns the recommended size for the ribbon.

Returns: The preferred size hint.

◆ slideInIdx()

void Ribbon::slideInIdx	(	uint04	idx,
		enum StackAnimationDirection	direction = StackAnimationDirection::e_automatic )

inlineoverridevirtual

Slides to the ribbon page at the given index with an optional animation direction.

Parameters

[in]	idx	The page index to slide to.
[in]	direction	The animation direction.

Reimplemented from QCustomStackedWidgetBase.

Definition at line 236 of file Ribbon.h.

References QCustomStackedWidgetBase::e_automatic, and QCustomStackedWidgetBase::slideInIdx().

The documentation for this class was generated from the following file:

Widgets/Headers/Ribbon.h

Public Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Ribbon()

Member Function Documentation

◆ _setVertical()

◆ addBottomRightWidget()

◆ addGroup() [1/4]

◆ addGroup() [2/4]

◆ addGroup() [3/4]

◆ addGroup() [4/4]

◆ addTopLeftWidget()

◆ group() [1/3]

◆ group() [2/3]

◆ group() [3/3]

◆ groupDock() [1/3]

◆ groupDock() [2/3]

◆ groupDock() [3/3]

◆ groups()

◆ hasGroup()

◆ isVertical()

◆ minimumSizeHint()

◆ operator[]()

◆ removeGroup() [1/3]

◆ removeGroup() [2/3]

◆ removeGroup() [3/3]

◆ section()

◆ setFixedNumOfRows()

◆ setGroupName()

◆ setInverseRibbonArea()

◆ setLayoutMode()

◆ setTabLock()

◆ sizeHint()

◆ slideInIdx()