The OverlayStackLayout re-implements a QStackedLayout with additional features to allow stacks with "floating" overlay widgets, such as toolbars, buttons, messages, etc., while still allowing interaction with exposed areas of the widget(s) underneath. More...

#include "OverlayStackLayout.h"

Inherits QStackedLayout.

Public Member Functions
	OverlayStackLayout (QWidget *parent=nullptr)
	Constructs a new `OverlayStackLayout` with the optional parent widget. More...

	OverlayStackLayout (QLayout *parentLayout)
	Constructs a new `OverlayStackLayout` and inserts it into the given parentLayout. More...

int	addWidget (QWidget *widget, Qt::Alignment alignment)
	Add widget to the stack with specified alignment. More...

int	addWidget (QWidget *widget, Qt::Alignment alignment, const QPoint &offset)
	Add widget to the stack with specified alignment and position offset coordinates. More...

int	addWidget (QWidget *widget)
	Inherited from `QStackedLayout::addWidget(QWidget *)` More...

int	insertWidget (int index, QWidget *widget, Qt::Alignment alignment)
	Insert widget into the stack at index position with specified alignment. More...

int	insertWidget (int index, QWidget *widget, Qt::Alignment alignment, const QPoint &offset)
	Insert widget into the stack at index position with specified alignment and position offset coordinates. More...

int	insertWidget (int index, QWidget *widget)
	Inherited from `QStackedLayout::insertWidget(int, QWidget *)` More...

void	setGeometry (const QRect &geo) override

Public Member Functions inherited from QStackedLayout
	QStackedLayout ()

	QStackedLayout (QWidget *parent)

	QStackedLayout (QLayout *parentLayout)

virtual	~QStackedLayout ()

virtual void	addItem (QLayoutItem *item) override

int	addWidget (QWidget *widget)

virtual int	count () const const override

void	currentChanged (int index)

int	currentIndex () const const

QWidget *	currentWidget () const const

virtual bool	hasHeightForWidth () const const override

virtual int	heightForWidth (int width) const const override

int	insertWidget (int index, QWidget *widget)

virtual QLayoutItem *	itemAt (int index) const const override

virtual const QMetaObject *	metaObject () const const

virtual QSize	minimumSize () const const override

virtual int	qt_metacall (QMetaObject::Call, int, void **)

virtual void *	qt_metacast (const char *)

void	setCurrentIndex (int index)

void	setCurrentWidget (QWidget *widget)

void	setStackingMode (QStackedLayout::StackingMode stackingMode)

virtual QSize	sizeHint () const const override

QStackedLayout::StackingMode	stackingMode () const const

virtual QLayoutItem *	takeAt (int index) override

QWidget *	widget (int index) const const

void	widgetRemoved (int index)

Public Member Functions inherited from QLayout
	QLayout (QWidget *parent)

	QLayout ()

bool	activate ()

void	addWidget (QWidget *w)

QMargins	contentsMargins () const const

QRect	contentsRect () const const

virtual QSizePolicy::ControlTypes	controlTypes () const const override

virtual Qt::Orientations	expandingDirections () const const override

virtual QRect	geometry () const const override

void	getContentsMargins (int left, int top, int right, int bottom) const const

virtual int	indexOf (QWidget *widget) const const

int	indexOf (QLayoutItem *layoutItem) const const

virtual void	invalidate () override

virtual bool	isEmpty () const const override

bool	isEnabled () const const

virtual QLayout *	layout () override

int	margin () const const

virtual QSize	maximumSize () const const override

QWidget *	menuBar () const const

QWidget *	parentWidget () const const

void	removeItem (QLayoutItem *item)

void	removeWidget (QWidget *widget)

QLayoutItem *	replaceWidget (QWidget from, QWidget to, Qt::FindChildOptions options)

bool	setAlignment (QLayout *l, Qt::Alignment alignment)

bool	setAlignment (QWidget *w, Qt::Alignment alignment)

void	setContentsMargins (int left, int top, int right, int bottom)

void	setContentsMargins (const QMargins &margins)

void	setEnabled (bool enable)

void	setMargin (int margin)

void	setMenuBar (QWidget *widget)

void	setSizeConstraint (QLayout::SizeConstraint)

void	setSpacing (int)

QLayout::SizeConstraint	sizeConstraint () const const

int	spacing () const const

void	update ()

Public Member Functions inherited from QObject
	QObject (QObject *parent)

virtual	~QObject ()

bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo () const const

void	dumpObjectInfo ()

void	dumpObjectTree () const const

void	dumpObjectTree ()

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QString &name, Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

void	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)

QThread *	thread () const const

Public Member Functions inherited from QLayoutItem
	QLayoutItem (Qt::Alignment alignment)

virtual	~QLayoutItem ()

Qt::Alignment	alignment () const const

virtual int	minimumHeightForWidth (int w) const const

void	setAlignment (Qt::Alignment alignment)

virtual QSpacerItem *	spacerItem ()

virtual QWidget *	widget ()

Public Slots
void	setOffset (QWidget *widget, const QPoint &offset) const
	Set the layout position offset coordinates for given widget. More...

void	setSenderAlignment (Qt::Alignment align)
	Convenience slot to set the layout alignment on a signal from a `QWidget::sender()`. More...

void	setSenderOffset (const QPoint &offset) const
	Convenience slot to set the layout position offset on a signal from a `QWidget::sender()`. More...

void	setStackingMode (StackingMode mode)
	Re-implemented (shadowing) `QStackedLayout::setStackingMode()` to ensure proper child visibility. More...

Additional Inherited Members
Public Types inherited from QStackedLayout
enum	StackingMode

Public Types inherited from QLayout
enum	SizeConstraint

Properties inherited from QStackedLayout
	count

	currentIndex

	stackingMode

Properties inherited from QLayout
	margin

	sizeConstraint

	spacing

Properties inherited from QObject
	objectName

Static Public Member Functions inherited from QStackedLayout
QString	tr (const char s, const char c, int n)

QString	trUtf8 (const char s, const char c, int n)

Static Public Member Functions inherited from QLayout
QSize	closestAcceptableSize (const QWidget *widget, const QSize &size)

QString	tr (const char s, const char c, int n)

QString	trUtf8 (const char s, const char c, int n)

Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

QString	tr (const char sourceText, const char disambiguation, int n)

QString	trUtf8 (const char sourceText, const char disambiguation, int n)

Public Attributes inherited from QStackedLayout
	StackAll

	StackOne

Public Attributes inherited from QLayout
	SetDefaultConstraint

	SetFixedSize

	SetMaximumSize

	SetMinAndMaxSize

	SetMinimumSize

	SetNoConstraint

Protected Member Functions inherited from QLayout
void	addChildLayout (QLayout *l)

void	addChildWidget (QWidget *w)

QRect	alignmentRect (const QRect &r) const const

virtual void	childEvent (QChildEvent *e) override

Protected Member Functions inherited from QObject
virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Detailed Description

The OverlayStackLayout re-implements a QStackedLayout with additional features to allow stacks with "floating" overlay widgets, such as toolbars, buttons, messages, etc., while still allowing interaction with exposed areas of the widget(s) underneath.

The functionality is similar to QStackedLayout::StackAll mode, but instead of forcing all child widgets to be the same size (as QStackedLayout does), this version respects the size hints of each widget. It also respects the widget alignment settings (like most other QLayouts), and adds a way to fine-tune the position with a positionOffset property which can be set on any widget. These are set with the standard QLayout::setAlignment() and custom OverlayStackLayout::setOffset() methods respectively. A few addWidget() and insertWidget() overloads are also provided to set these properties at insertion time.

So for example one could have a "main" widget with QSizePolicy::Expanding flags in both directions which will take up the full size of the layout. Then add a toolbar with fixed/minimum size policy and Qt::AlignTop | Qt::AlignHCenter alignment which will "float" on top of the main widget and keep itself centered in the available width. Only the actual toolbar area would capture mouse events, so interaction with the main area widget is still possible. The toolbar could be spaced away from the top of the window using the positionOffset property with a positive y value.

QWidget *w = new QWidget();  // Container widget for stack layout
// overlay layout for the container, toolbar will "float" on top of main widget
OverlayStackLayout *lo = new OverlayStackLayout(w);
lo->setContentsMargins(0,0,0,0);    // Clear the default margins
QWidget *main = new QWidget(w);     // A content widget
main->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);  // stretch to fit
Toolbar *toolbar = new Toolbar(w);  // A floating toolbar
// Add the main widget
lo->addWidget(main);
// Add toolbar widget with center/top alignment and 20px vertical offset
lo->addWidget(toolbar, Qt::AlignTop | Qt::AlignHCenter, QPoint(0, 20));
lo->setCurrentIndex(1);  // stack toolbar on top

OverlayStackLayout also respects the Qt::WA_LayoutOnEntireRect widget attribute. Widgets with this attribute set will always be laid out ignoring any contentsMargins() set on this layout (that is, using the full available geometry() size, vs. contentsRect() size). This allows some widgets to be spaced away from the edges, while others cover the full available area. Using the example above, the toolbar could be spaced away from the top by setting a positive top content margin on the layout, and setting the Qt::WA_LayoutOnEntireRect attribute on the main expanding widget.

By default the layout operates in QStackedLayout::StackAll mode, meaning no widgets are hidden when changing the currentIndex, only the stack order changes. However, the QStackedLayout::StackOne mode can also be used, for example to switch between multiple pages like a "typical" stack. In this mode the Qt::WA_LayoutOnEntireRect widget attribute could be set to ensure one or more widgets are always stacked on top of others.

Here is another example showing the above concepts in action.

MyWidget() : QWidget()
{
  OverlayStackLayout *stackLo = new OverlayStackLayout(this);

  // We will use the stack layout for switching pages as well as floating a menu button and info text overlay.
  stackLo->setStackingMode(OverlayStackLayout::StackOne);
  // Keep main floating menu button in the SE corner away from bottom/right edge of window.
  stackLo->setContentsMargins(0,0,15,15);

  // Create a page widget which will be shown full-size underneath the main toolbar.
  QWidget *w = new QWidget(this);
  w->setAttribute(Qt::WA_LayoutOnEntireRect);  // ignore main stack layout margins
  w->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);  // stretch to fit
  stackLo->addWidget(w);  // add to main stack view

// ... create more page widgets...

// main app "floating" menu toolbar/button with common options

Toolbar *mainToolbar = new Toolbar(this);

  // Keep toolbar on top of all other widgets, regardless of "currentIndex()" page.
  mainToolbar->setAttribute(Qt::WA_AlwaysStackOnTop);
  // Add menu button to the overlay layout in the bottom right corner
  stackLo->addWidget(mainToolbar, Qt::AlignRight | Qt::AlignBottom);

}

Note that for non-interactive overlays (eg. messages/information), one can set the Qt::WA_TransparentForMouseEvents widget attribute to avoid interference with any underlying widgets altogether.

A complete example application demonstrating the different uses of OverlayStackLayout is available in the /examples/imageviewer folder of this project.

See also: QStackedLayout

Definition at line 108 of file OverlayStackLayout.h.

Constructor & Destructor Documentation

◆ OverlayStackLayout() [1/2]

OverlayStackLayout::OverlayStackLayout ( QWidget * parent = nullptr )

explicit

Constructs a new OverlayStackLayout with the optional parent widget.

If parent is specified, this layout will install itself on the parent widget.

Definition at line 36 of file OverlayStackLayout.cpp.

◆ OverlayStackLayout() [2/2]

OverlayStackLayout::OverlayStackLayout ( QLayout * parentLayout )

explicit

Constructs a new OverlayStackLayout and inserts it into the given parentLayout.

Definition at line 42 of file OverlayStackLayout.cpp.

Member Function Documentation

◆ addWidget() [1/3]

int OverlayStackLayout::addWidget	(	QWidget *	widget,
		Qt::Alignment	alignment
	)

inline

Add widget to the stack with specified alignment.

See also: QStackedLayout::addWidget()

Definition at line 165 of file OverlayStackLayout.h.

◆ addWidget() [2/3]

int OverlayStackLayout::addWidget	(	QWidget *	widget,
		Qt::Alignment	alignment,
		const QPoint &	offset
	)

inline

Add widget to the stack with specified alignment and position offset coordinates.

See also: QStackedLayout::addWidget()

Definition at line 171 of file OverlayStackLayout.h.

◆ addWidget() [3/3]

int QStackedLayout::addWidget

Inherited from QStackedLayout::addWidget(QWidget *)

◆ insertWidget() [1/3]

int OverlayStackLayout::insertWidget	(	int	index,
		QWidget *	widget,
		Qt::Alignment	alignment
	)

Insert widget into the stack at index position with specified alignment.

See also: QStackedLayout::insertWidget()

Definition at line 48 of file OverlayStackLayout.cpp.

◆ insertWidget() [2/3]

int OverlayStackLayout::insertWidget	(	int	index,
		QWidget *	widget,
		Qt::Alignment	alignment,
		const QPoint &	offset
	)

Insert widget into the stack at index position with specified alignment and position offset coordinates.

See also: QStackedLayout::insertWidget()

Definition at line 56 of file OverlayStackLayout.cpp.

◆ insertWidget() [3/3]

int QStackedLayout::insertWidget

Inherited from QStackedLayout::insertWidget(int, QWidget *)

◆ setGeometry()

void OverlayStackLayout::setGeometry ( const QRect & geo )

overridevirtual

Reimplemented from QStackedLayout.

Definition at line 94 of file OverlayStackLayout.cpp.

◆ setOffset

void OverlayStackLayout::setOffset	(	QWidget *	widget,
		const QPoint &	offset
	)		const

slot

Set the layout position offset coordinates for given widget.

The offset is in absolute pixels and is applied after alignment positioning.

Note: Note that you can also simply assign a property named "positionOffset" with a QPoint type value to any widget and it will be respected by this layout.

Definition at line 64 of file OverlayStackLayout.cpp.

◆ setSenderAlignment

void OverlayStackLayout::setSenderAlignment ( Qt::Alignment align )

slot

Convenience slot to set the layout alignment on a signal from a QWidget::sender().

This has no effect if the sender widget is not currently in this layout.

See also: setAlignment()

Definition at line 78 of file OverlayStackLayout.cpp.

◆ setSenderOffset

void OverlayStackLayout::setSenderOffset ( const QPoint & offset ) const

slot

Convenience slot to set the layout position offset on a signal from a QWidget::sender().

This has no effect if the sender widget is not currently in this layout.

See also: setOffset()

Definition at line 72 of file OverlayStackLayout.cpp.

◆ setStackingMode

void OverlayStackLayout::setStackingMode ( QStackedLayout::StackingMode mode )

slot

Re-implemented (shadowing) QStackedLayout::setStackingMode() to ensure proper child visibility.

The default stacking mode for OverlayStackLayout is QStackedLayout::StackAll.

Note: Setting the stacking mode to QStackedLayout::StackOne when currentIndex() > 0 will hide (setVisible(false)) all widgets except the current one. Conversely, setting the mode to StackAll will set all widgets to be visible. This is due to how QStackedLayout::setStackingMode() operates. In general it is recommended to set the desired stacking mode before adding widgets.

Definition at line 84 of file OverlayStackLayout.cpp.

Public Member Functions

Public Slots

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ OverlayStackLayout() [1/2]

◆ OverlayStackLayout() [2/2]

Member Function Documentation

◆ addWidget() [1/3]

◆ addWidget() [2/3]

◆ addWidget() [3/3]

◆ insertWidget() [1/3]

◆ insertWidget() [2/3]

◆ insertWidget() [3/3]

◆ setGeometry()

◆ setOffset

◆ setSenderAlignment

◆ setSenderOffset

◆ setStackingMode