The DockWidget base-class. DockWidget and DockWidgetBase are only split in two so we can share some code with the QtQuick implementation, which also derives from DockWidgetBase. More...

#include <DockWidgetBase.h>

Inheritance diagram for KDDockWidgets::DockWidgetBase:

[legend]

Collaboration diagram for KDDockWidgets::DockWidgetBase:

[legend]

Public Types
enum	IconPlace { TitleBar = 1, TabBar = 2, All = TitleBar \| TabBar }

typedef QVector< DockWidgetBase * >	List

enum	Option { Option_None = 0, Option_NotClosable = 1, Option_NotDockable = 2 }
	DockWidget options to pass at construction time. More...

Signals
void	hidden ()
	signal emitted when the DockWidget is hidden. As in QEvent::Hide.

void	iconChanged ()
	signal emitted when the icon changed

bool	isFloatingChanged (bool)
	emitted when isFloating changes

void	isFocusedChanged (bool)
	emitted when isFocused changes More...

void	isOverlayedChanged (bool)
	emitted when isOverlayed changes More...

void	optionsChanged (KDDockWidgets::DockWidgetBase::Options)
	emitted when the options change More...

void	parentChanged ()
	signal emitted when the parent changed

void	removedFromSideBar ()
	emitted when this dock widget is removed from a side-bar. Only relevant for the auto-hide/sidebar feature

void	shown ()
	signal emitted when the DockWidget is shown. As in QEvent::Show.

void	titleChanged (const QString &title)
	signal emitted when the title changed More...

void	widgetChanged (KDDockWidgets::QWidgetOrQuick *)
	emitted when the hosted widget changed

Public Member Functions
	DockWidgetBase (const QString &uniqueName, Options options=DockWidgetBase::Options())
	constructs a new DockWidget More...

	~DockWidgetBase () override
	destructor

void	addDockWidgetAsTab (DockWidgetBase *other, AddingOption addingOption=AddingOption_None)
	docks `other` widget into this one. Tabs will be shown if not already. More...

void	addDockWidgetToContainingWindow (DockWidgetBase other, KDDockWidgets::Location location, DockWidgetBase relativeTo=nullptr)
	docks `other` widget into the window that contains this one. Equivalent to MainWindow::addDockWidget() with the difference that it also supports the case where the top-level window is a FloatingWindow instead of MainWindow. More...

QStringList	affinities () const
	Returns the affinity name. Empty by default.

QAction *	floatAction () const
	Returns the QAction that allows to dock/undock the dock widget Useful to put in menus.

void	forceClose ()
	Like QWidget::close() but the hosted widget won't be asked if we should close.

bool	hasPreviousDockedLocation () const
	Returns whether this floating dock widget knows its previous docked location Result only makes sense if it's floating. More...

QIcon	icon (IconPlace place=IconPlace::TitleBar) const
	Returns the dock widget's titlebar or tabbar icon (depending on the passed `place`) More...

bool	isCurrentTab () const
	Returns true if this dock widget is the current one in the tab widget that contains it. If the dock widget is alone then true is returned, as in this case there will also be a tab widget even though it's invisible.

bool	isFloating () const
	Returns whether the dock widget is floating. Floating means it's not docked and has a window of its own. Note that if you dock a floating dock widget into another floating one then they don't count as floating anymore, as they are side-by-side (or tabbed).

bool	isFocused () const
	Returns whether This or any child of this dock widget is focused Not to be confused with QWidget::hasFocus(), which just refers to 1 widget. This includes variant includes children. More...

bool	isInMainWindow () const
	Returns whether this dock widget is docked into a main window. More...

bool	isMainWindow () const
	Returns whether widget() is a KDDockWidget::MainWindow. More...

bool	isOpen () const
	Returns whether this dock widget is open. Equivalent to calling toggleAction().isChecked() or isVisible()

bool	isOverlayed () const
	Returns whether this dock widget is overlayed on top of the main window, instead of docked into the layout. This is only relevant when using the auto-hide and side-bar feature.

bool	isTabbed () const
	returns if this dock widget is tabbed into another More...

MainWindowBase *	mainWindow () const
	Returns the main window this dock widget is in. nullptr if it's not inside a main window.

void	moveToSideBar ()
	Minimizes this dock widget to the MainWindow's side-bar. More...

Options	options () const
	Returns the dock widget's options which control behaviour. More...

void	raise ()
	Brings the dock widget to the front. More...

LayoutSaver::DockWidget::Ptr	serialize () const
	Serializes this dock widget into an intermediate form.

void	setAffinities (const QStringList &)
	Sets the affinity names. Dock widgets can only dock into dock widgets of the same affinity. More...

void	setAffinityName (const QString &name)

void	setAsCurrentTab ()
	Makes this dock widget current in its tab group.

bool	setFloating (bool floats)
	setter to make the dock widget float or dock. More...

void	setIcon (const QIcon &icon, IconPlaces places=IconPlace::All)
	Sets an icon to show on title bars and tab bars. More...

void	setOptions (Options)
	Setter for the options. Only Option_NotClosable is allowed to change after construction. For the other options use the constructor only. More...

void	setTitle (const QString &title)
	setter for the dock widget's title More...

virtual void	setWidget (QWidgetOrQuick *widget)
	sets the widget which this dock widget hosts. More...

void	show ()
	Equivalent to QWidget::show(), but it's optimized to reduce flickering on some platforms.

SideBarLocation	sideBarLocation () const
	Returns whether this dock widget is in a side bar, and which. SideBarLocation::None is returned if it's not in a sidebar. This is only relevant when using the auto-hide and side-bar feature.

QString	title () const
	Returns the dock widget's title. This title is visible in title bars and tab bars. More...

TitleBar *	titleBar () const
	Returns this dock widget's title bar. More...

QAction *	toggleAction () const
	Returns the QAction that allows to hide/show the dock widget Useful to put in menus.

QString	uniqueName () const
	the dock widget's unique name. More...

QWidgetOrQuick *	widget () const
	returns the widget which this dock widget hosts

Static Public Member Functions
static DockWidgetBase *	deserialize (const LayoutSaver::DockWidget::Ptr &)
	Constructs a dock widget from its serialized form. More...

Protected Member Functions
void	onClosed (QCloseEvent *e)

void	onHidden (bool spontaneous)

void	onParentChanged ()

void	onShown (bool spontaneous)

Properties
bool	isFloating

bool	isFocused

Detailed Description

The DockWidget base-class. DockWidget and DockWidgetBase are only split in two so we can share some code with the QtQuick implementation, which also derives from DockWidgetBase.

Do not use instantiate directly in user code. Use DockWidget instead.

Member Enumeration Documentation

enum KDDockWidgets::DockWidgetBase::Option

DockWidget options to pass at construction time.

Enumerator

Option_None

No option, the default.

Option_NotDockable

The DockWidget can't be closed on the [x], only programatically.

The DockWidget can't be docked, it's always floating

Constructor & Destructor Documentation

DockWidgetBase::DockWidgetBase	(	const QString &	uniqueName,
		Options	options = `DockWidgetBase::Options()`
	)

explicit

constructs a new DockWidget

Parameters

uniqueName	the name of the dockwidget, should be unique. Use title for user visible text.
options	optional options controlling behaviour

There's no parent argument. The DockWidget is either parented to FloatingWindow or MainWindow when visible, or stays without a parent when hidden.

Member Function Documentation

void DockWidgetBase::addDockWidgetAsTab	(	DockWidgetBase *	other,
		AddingOption	addingOption = `AddingOption_None`
	)

docks other widget into this one. Tabs will be shown if not already.

Parameters

other	The other dock widget to dock into this one.
addingOption	Allows to specify an AddingOption. Which is useful to add the dock widget as hidden, recording only a placeholder in the tab. So it's restored to tabbed when eventually shown.

See also: MainWindow::addDockWidget(), DockWidget::addDockWidgetToContainingWindow()

void DockWidgetBase::addDockWidgetToContainingWindow	(	DockWidgetBase *	other,
		KDDockWidgets::Location	location,
		DockWidgetBase *	relativeTo = `nullptr`
	)

docks other widget into the window that contains this one. Equivalent to MainWindow::addDockWidget() with the difference that it also supports the case where the top-level window is a FloatingWindow instead of MainWindow.

Parameters

other	The other dock widget to dock into the window.
location	The location to dock.
relativeTo	The dock widget that the `location` is relative to. If null then the window is considered.

See also: MainWindow::addDockWidget(), DockWidget::addDockWidgetAsTab()

DockWidgetBase * DockWidgetBase::deserialize ( const LayoutSaver::DockWidget::Ptr & saved )

static

Constructs a dock widget from its serialized form.

bool DockWidgetBase::hasPreviousDockedLocation ( ) const

Returns whether this floating dock widget knows its previous docked location Result only makes sense if it's floating.

When you call dockWidget->setFloating(false) it will only dock if it knows where to.

QIcon DockWidgetBase::icon ( IconPlace place = IconPlace::TitleBar ) const

Returns the dock widget's titlebar or tabbar icon (depending on the passed place)

By default it's null.

See also: setIcon()

bool KDDockWidgets::DockWidgetBase::isFocused ( ) const

Returns whether This or any child of this dock widget is focused Not to be confused with QWidget::hasFocus(), which just refers to 1 widget. This includes variant includes children.

See also: isFocusedChanged()

void KDDockWidgets::DockWidgetBase::isFocusedChanged ( bool )

signal

emitted when isFocused changes

See also: isFocused

bool DockWidgetBase::isInMainWindow ( ) const

Returns whether this dock widget is docked into a main window.

Note that isFloating() returning false might either mean the dock widget is docked into a main window or into a floating window (groupped/nested with other dock widgets. Use this function then if you need to disambiguate

bool DockWidgetBase::isMainWindow ( ) const

Returns whether widget() is a KDDockWidget::MainWindow.

This function doesn't have anything to do with this dock widget being inside a main window or not, but rather the inverse concept. It's not a very popular usage, but some applications want to dock a main window into another main window. This is done by putting it into a dock widget first.

See also kddockwidgets_example -j

void KDDockWidgets::DockWidgetBase::isOverlayedChanged ( bool )

signal

emitted when isOverlayed changes

See also: isOverlayed

bool DockWidgetBase::isTabbed ( ) const

returns if this dock widget is tabbed into another

Technically a docked DockWidget always lives in a tab widget, but from the user's prespective it's not tabbed when there's only 1 dock widget, as there are no tabs displayed. Unless the frame is using Option_AlwaysShowsTabs, in which case this method will return true regardless if being the single one.

void DockWidgetBase::moveToSideBar ( )

Minimizes this dock widget to the MainWindow's side-bar.

It will be undocked from current layout. It's previous docked position will be remembered.

This action is only available if the dock widget is docked into a MainWindow. The dockwidget will initially be visible and overlayed on top of the current layout (this is the auto-hide feature).

DockWidgetBase::Options DockWidgetBase::options ( ) const

Returns the dock widget's options which control behaviour.

See also: setOptions(), optionsChanged()

void KDDockWidgets::DockWidgetBase::optionsChanged ( KDDockWidgets::DockWidgetBase::Options )

signal

emitted when the options change

See also: setOptions(), options()

void DockWidgetBase::raise ( )

Brings the dock widget to the front.

This means:

If the dock widget is tabbed with other dock widgets but its tab is not current, it's made current.
If the dock widget is floating, QWindow::raise() is called.

This only applies if the dock widget is already open. If closed, does nothing.

void DockWidgetBase::setAffinities ( const QStringList & affinityNames )

Sets the affinity names. Dock widgets can only dock into dock widgets of the same affinity.

By default the affinity is empty and a dock widget can dock into any main window and into any floating window. Usually you won't ever need to call this function, unless you have requirements where certain dock widgets can only dock into certain other dock widgets and main windows.

See also: MainWindowBase::setAffinities().

Note: Call this function right after creating your dock widget, before adding to a main window and before restoring any layout.

Note: Currently you can only call this function once, to keep the code simple and avoid edge cases. This will only be changed if a good use case comes up that requires changing affinities multiple times.

names the affinity names

void DockWidgetBase::setAffinityName ( const QString & name )

Deprecated:: This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

name	the affinity name

bool DockWidgetBase::setFloating ( bool floats )

setter to make the dock widget float or dock.

Parameters

floats If true makes the dock widget float, otherwise docks it.

Returns true if the request was accomplished

void DockWidgetBase::setIcon	(	const QIcon &	icon,
		IconPlaces	places = `IconPlace::All`
	)

Sets an icon to show on title bars and tab bars.

Parameters

places Specifies where the icon will be shown (TitleBar, TabBar or both)

By default there's no icon set.

See also: icon()

void DockWidgetBase::setOptions ( Options options )

Setter for the options. Only Option_NotClosable is allowed to change after construction. For the other options use the constructor only.

See also: options(), optionsChanged()

void DockWidgetBase::setTitle ( const QString & title )

setter for the dock widget's title

Parameters

title the dock widget's new title

See also: setTitle

void DockWidgetBase::setWidget ( QWidgetOrQuick * widget )

virtual

sets the widget which this dock widget hosts.

Parameters

widget the widget to show inside this dock widget. Must not be null.

Ownership for widget is transferred to DockWidgetBase. Ownsership for any previously existing widget is transferred back to the user. Meaning if you call setWidget(A) followed by setWidget(B) then A will have to be deleted by you, while B is owned by the dock widget.

QString DockWidgetBase::title ( ) const

Returns the dock widget's title. This title is visible in title bars and tab bars.

See also: setTitle

TitleBar * DockWidgetBase::titleBar ( ) const

Returns this dock widget's title bar.

Note that several dock widgets can have the same title bar, in case they are tabbed together. Hidden dock widgets have no associated title bar.

void KDDockWidgets::DockWidgetBase::titleChanged ( const QString & title )

signal

signal emitted when the title changed

Parameters

title the new title

QString DockWidgetBase::uniqueName ( ) const

the dock widget's unique name.

Public Types

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Properties

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation