#include <DockWidget.h>

Inheritance diagram for ads::CDockWidget:

Public Types
enum	DockWidgetFeature { DockWidgetClosable = 0x01, DockWidgetMovable = 0x02, DockWidgetFloatable = 0x04, DockWidgetDeleteOnClose = 0x08, CustomCloseHandling = 0x10, DockWidgetFocusable = 0x20, DockWidgetForceCloseWithArea = 0x40, DefaultDockWidgetFeatures = DockWidgetClosable \| DockWidgetMovable \| DockWidgetFloatable \| DockWidgetFocusable, AllDockWidgetFeatures = DefaultDockWidgetFeatures \| DockWidgetDeleteOnClose \| CustomCloseHandling, DockWidgetAlwaysCloseAndDelete = DockWidgetForceCloseWithArea \| DockWidgetDeleteOnClose, NoDockWidgetFeatures = 0x00 }

enum	eInsertMode { AutoScrollArea, ForceScrollArea, ForceNoScrollArea }

enum	eMinimumSizeHintMode { MinimumSizeHintFromDockWidget, MinimumSizeHintFromContent }

enum	eState { StateHidden, StateDocked, StateFloating }

enum	eToggleViewActionMode { ActionModeToggle, ActionModeShow }

using	Super = QFrame

Public Slots
void	closeDockWidget ()

void	deleteDockWidget ()

void	raise ()

void	setAsCurrentTab ()

void	setFloating ()

void	showFullScreen ()

void	showNormal ()

void	toggleView (bool Open=true)

Signals
void	closed ()

void	closeRequested ()

void	featuresChanged (ads::CDockWidget::DockWidgetFeatures features)

void	titleChanged (const QString &Title)

void	topLevelChanged (bool topLevel)

void	viewToggled (bool Open)

void	visibilityChanged (bool visible)

Public Member Functions
	CDockWidget (const QString &title, QWidget *parent=0)

QToolBar *	createDefaultToolBar ()

CDockAreaWidget *	dockAreaWidget () const

CDockContainerWidget *	dockContainer () const

CDockManager *	dockManager () const

virtual bool	event (QEvent *e) override

DockWidgetFeatures	features () const

QIcon	icon () const

bool	isCentralWidget () const

bool	isClosed () const

bool	isCurrentTab () const

bool	isFloating () const

bool	isFullScreen () const

bool	isInFloatingContainer () const

bool	isTabbed () const

virtual QSize	minimumSizeHint () const override

void	setFeature (DockWidgetFeature flag, bool on)

void	setFeatures (DockWidgetFeatures features)

void	setIcon (const QIcon &Icon)

void	setMinimumSizeHintMode (eMinimumSizeHintMode Mode)

void	setTabToolTip (const QString &text)

void	setTitleBarActions (QList< QAction * > actions)

void	setToggleViewActionMode (eToggleViewActionMode Mode)

void	setToolBar (QToolBar *ToolBar)

void	setToolBarIconSize (const QSize &IconSize, eState State)

void	setToolBarStyle (Qt::ToolButtonStyle Style, eState State)

void	setWidget (QWidget *widget, eInsertMode InsertMode=AutoScrollArea)

CDockWidgetTab *	tabWidget () const

QWidget *	takeWidget ()

virtual QList< QAction * >	titleBarActions () const

QAction *	toggleViewAction () const

QToolBar *	toolBar () const

QSize	toolBarIconSize (eState State) const

Qt::ToolButtonStyle	toolBarStyle (eState State) const

QWidget *	widget () const

virtual	~CDockWidget ()

Protected Member Functions
bool	closeDockWidgetInternal (bool ForceClose=false)

void	emitTopLevelChanged (bool Floating)

void	flagAsUnassigned ()

void	saveState (QXmlStreamWriter &Stream) const

void	setClosedState (bool Closed)

void	setDockArea (CDockAreaWidget *DockArea)

void	setDockManager (CDockManager *DockManager)

void	setToggleViewActionChecked (bool Checked)

void	toggleViewInternal (bool Open)

Static Protected Member Functions
static void	emitTopLevelEventForWidget (CDockWidget *TopLevelDockWidget, bool Floating)

Private Slots
void	setToolbarFloatingStyle (bool topLevel)

Private Attributes
DockWidgetPrivate *	d
	private data (pimpl) More...

Friends
class	CDockAreaTabBar

class	CDockAreaWidget

class	CDockContainerWidget

class	CDockManager

class	CDockWidgetTab

class	CFloatingDockContainer

struct	DockAreaTitleBarPrivate

class	DockContainerWidgetPrivate

struct	DockManagerPrivate

struct	DockWidgetPrivate

struct	DockWidgetTabPrivate

Detailed Description

The QDockWidget class provides a widget that can be docked inside a CDockManager or floated as a top-level window on the desktop.

Definition at line 54 of file DockWidget.h.

Member Typedef Documentation

using ads::CDockWidget::Super = QFrame

Definition at line 146 of file DockWidget.h.

Member Enumeration Documentation

enum ads::CDockWidget::DockWidgetFeature

Enumerator
DockWidgetClosable	dock widget has a close button
DockWidgetMovable	dock widget is movable and can be moved to a new position in the current dock container
DockWidgetFloatable	dock widget can be dragged into a floating window
DockWidgetDeleteOnClose	deletes the dock widget when it is closed
CustomCloseHandling	clicking the close button will not close the dock widget but emits the closeRequested() signal instead
DockWidgetFocusable	if this is enabled, a dock widget can get focus highlighting
DockWidgetForceCloseWithArea	dock widget will be closed when the dock area hosting it is closed
DefaultDockWidgetFeatures
AllDockWidgetFeatures
DockWidgetAlwaysCloseAndDelete
NoDockWidgetFeatures

Definition at line 148 of file DockWidget.h.

enum ads::CDockWidget::eInsertMode

Sets the widget for the dock widget to widget. The InsertMode defines how the widget is inserted into the dock widget. The content of a dock widget should be resizable do a very small size to prevent the dock widget from blocking the resizing. To ensure, that a dock widget can be resized very well, it is better to insert the content+ widget into a scroll area or to provide a widget that is already a scroll area or that contains a scroll area. If the InsertMode is AutoScrollArea, the DockWidget tries to automatically detect how to insert the given widget. If the widget is derived from QScrollArea (i.e. an QAbstractItemView), then the widget is inserted directly. If the given widget is not a scroll area, the widget will be inserted into a scroll area. To force insertion into a scroll area, you can also provide the InsertMode ForceScrollArea. To prevent insertion into a scroll area, you can provide the InsertMode ForceNoScrollArea

Enumerator
AutoScrollArea
ForceScrollArea
ForceNoScrollArea

Definition at line 188 of file DockWidget.h.

enum ads::CDockWidget::eMinimumSizeHintMode

The mode of the minimumSizeHint() that is returned by the DockWidget minimumSizeHint() function. To ensure, that a dock widget does not block resizing, the dock widget reimplements minimumSizeHint() function to return a very small minimum size hint. If you would like to adhere the minimumSizeHint() from the content widget, then set the minimumSizeHintMode() to MinimumSizeHintFromContent.

Enumerator
MinimumSizeHintFromDockWidget
MinimumSizeHintFromContent

Definition at line 205 of file DockWidget.h.

enum ads::CDockWidget::eState

Enumerator
StateHidden
StateDocked
StateFloating

Definition at line 164 of file DockWidget.h.

enum ads::CDockWidget::eToggleViewActionMode

This mode configures the behavior of the toggle view action. If the mode if ActionModeToggle, then the toggle view action is a checkable action to show / hide the dock widget. If the mode is ActionModeShow, then the action is not checkable an it will always show the dock widget if clicked. If the mode is ActionModeShow, the user can only close the DockWidget with the close button.

Enumerator
ActionModeToggle	ActionModeToggle.
ActionModeShow	ActionModeShow.

Definition at line 220 of file DockWidget.h.

Constructor & Destructor Documentation

ads::CDockWidget::CDockWidget	(	const QString &	title,
		QWidget *	parent = `0`
	)

This constructor creates a dock widget with the given title. The title is the text that is shown in the window title when the dock widget is floating and it is the title that is shown in the titlebar or the tab of this dock widget if it is tabified. The object name of the dock widget is also set to the title. The object name is required by the dock manager to properly save and restore the state of the dock widget. That means, the title needs to be unique. If your title is not unique or if you would like to change the title during runtime, you need to set a unique object name explicitely by calling setObjectName() after construction. Use the layoutFlags to configure the layout of the dock widget.

Definition at line 223 of file DockWidget.cpp.

ads::CDockWidget::~CDockWidget ( )

virtual

Virtual Destructor

Definition at line 248 of file DockWidget.cpp.

Member Function Documentation

void ads::CDockWidget::closed ( )

signal

This signal is emitted if the dock widget is closed

void ads::CDockWidget::closeDockWidget ( )

slot

Closes the dock widget

Definition at line 836 of file DockWidget.cpp.

bool ads::CDockWidget::closeDockWidgetInternal ( bool ForceClose = false )

protected

Internal close dock widget implementation. The function returns true if the dock widget has been closed or hidden

Definition at line 843 of file DockWidget.cpp.

void ads::CDockWidget::closeRequested ( )

signal

This signal is emitted, if close is requested

QToolBar * ads::CDockWidget::createDefaultToolBar ( )

If you would like to use the default top tool bar, then call this function to create the default tool bar. After this function the toolBar() function will return a valid toolBar() object.

Definition at line 664 of file DockWidget.cpp.

void ads::CDockWidget::deleteDockWidget ( )

slot

This function will delete the dock widget and its content from the docking system

Definition at line 827 of file DockWidget.cpp.

CDockAreaWidget * ads::CDockWidget::dockAreaWidget ( ) const

Returns the dock area widget this dock widget belongs to or 0 if this dock widget has not been docked yet

Definition at line 394 of file DockWidget.cpp.

CDockContainerWidget * ads::CDockWidget::dockContainer ( ) const

Returns the dock container widget this dock area widget belongs to or 0 if this dock widget has not been docked yet

Definition at line 380 of file DockWidget.cpp.

CDockManager * ads::CDockWidget::dockManager ( ) const

Returns the dock manager that manages the dock widget or 0 if the widget has not been assigned to any dock manager yet

Definition at line 366 of file DockWidget.cpp.

void ads::CDockWidget::emitTopLevelChanged ( bool Floating )

protected

Use this function to emit a top level changed event. Do never use emit topLevelChanged(). Always use this function because it only emits a signal if the floating state has really changed

Definition at line 784 of file DockWidget.cpp.

void ads::CDockWidget::emitTopLevelEventForWidget	(	CDockWidget *	TopLevelDockWidget,
		bool	Floating
	)

staticprotected

Call this function to emit a topLevelChanged() signal and to update the dock area tool bar visibility

Definition at line 773 of file DockWidget.cpp.

bool ads::CDockWidget::event ( QEvent * e )

overridevirtual

Emits titleChanged signal if title change event occurs

Definition at line 579 of file DockWidget.cpp.

CDockWidget::DockWidgetFeatures ads::CDockWidget::features ( ) const

This property holds whether the dock widget is movable, closable, and floatable. By default, this property is set to a combination of DockWidgetClosable, DockWidgetMovable and DockWidgetFloatable.

Definition at line 359 of file DockWidget.cpp.

void ads::CDockWidget::featuresChanged ( ads::CDockWidget::DockWidgetFeatures features )

signal

This signal is emitted when the features property changes. The features parameter gives the new value of the property.

void ads::CDockWidget::flagAsUnassigned ( )

protected

This is a helper function for the dock manager to flag this widget as unassigned. When calling the restore function, it may happen, that the saved state contains less dock widgets then currently available. All widgets whose data is not contained in the saved state, are flagged as unassigned after the restore process. If the user shows an unassigned dock widget, a floating widget will be created to take up the dock widget.

Definition at line 568 of file DockWidget.cpp.

QIcon ads::CDockWidget::icon ( ) const

Returns the icon that has been assigned to the dock widget

Definition at line 650 of file DockWidget.cpp.

bool ads::CDockWidget::isCentralWidget ( ) const

Returns true if the dock widget is set as central widget of it's dock manager

Definition at line 468 of file DockWidget.cpp.

bool ads::CDockWidget::isClosed ( ) const

Returns true, if this dock widget is closed.

Definition at line 431 of file DockWidget.cpp.

bool ads::CDockWidget::isCurrentTab ( ) const

Returns true if this dock widget is the current one in the dock area widget that contains it. If the dock widget is the only opened dock widget in a dock area, the true is returned

Definition at line 959 of file DockWidget.cpp.

bool ads::CDockWidget::isFloating ( ) const

This property holds whether the dock widget is floating. A dock widget is only floating, if it is the one and only widget inside of a floating container. If there are more than one dock widget in a floating container, the all dock widgets are docked and not floating.

Definition at line 401 of file DockWidget.cpp.

bool ads::CDockWidget::isFullScreen ( ) const

Returns true if the dock widget is floating and if the floating dock container is full screen

Definition at line 927 of file DockWidget.cpp.

bool ads::CDockWidget::isInFloatingContainer ( ) const

This function returns true, if this dock widget is in a floating. The function returns true, if the dock widget is floating and it also returns true if it is docked inside of a floating container.

Definition at line 413 of file DockWidget.cpp.

bool ads::CDockWidget::isTabbed ( ) const

Returns true if this dock widget is in a dock area, that contains at least 2 opened dock widgets

Definition at line 951 of file DockWidget.cpp.

QSize ads::CDockWidget::minimumSizeHint ( ) const

overridevirtual

We return a fixed minimum size hint or the size hint of the content widget if minimum size hint mode is MinimumSizeHintFromContent

Definition at line 802 of file DockWidget.cpp.

void ads::CDockWidget::raise ( )

slot

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.

Definition at line 966 of file DockWidget.cpp.

void ads::CDockWidget::saveState ( QXmlStreamWriter & Stream ) const

protected

Saves the state into the given stream

Definition at line 558 of file DockWidget.cpp.

void ads::CDockWidget::setAsCurrentTab ( )

slot

Makes this dock widget the current tab in its dock area. The function only has an effect, if the dock widget is open. A call to this function will not toggle the view, so if it is closed, nothing will happen

Definition at line 941 of file DockWidget.cpp.

void ads::CDockWidget::setClosedState ( bool Closed )

protected

Internal function for modifying the closed state when restoring a saved docking state

Definition at line 795 of file DockWidget.cpp.

void ads::CDockWidget::setDockArea ( CDockAreaWidget * DockArea )

protected

If this dock widget is inserted into a dock area, the dock area will be registered on this widget via this function. If a dock widget is removed from a dock area, this function will be called with nullptr value.

Definition at line 549 of file DockWidget.cpp.

void ads::CDockWidget::setDockManager ( CDockManager * DockManager )

protected

Assigns the dock manager that manages this dock widget

Definition at line 373 of file DockWidget.cpp.

void ads::CDockWidget::setFeature	(	DockWidgetFeature	flag,
		bool	on
	)

Sets the feature flag for this dock widget if on is true; otherwise clears the flag.

Definition at line 350 of file DockWidget.cpp.

void ads::CDockWidget::setFeatures ( DockWidgetFeatures features )

Sets, whether the dock widget is movable, closable, and floatable.

Definition at line 335 of file DockWidget.cpp.

void ads::CDockWidget::setFloating ( )

slot

This function will make a docked widget floating

Definition at line 816 of file DockWidget.cpp.

void ads::CDockWidget::setIcon ( const QIcon & Icon )

Sets the dock widget icon that is shown in tabs and in toggle view actions

Definition at line 639 of file DockWidget.cpp.

void ads::CDockWidget::setMinimumSizeHintMode ( eMinimumSizeHintMode Mode )

Configures the minimum size hint that is returned by the minimumSizeHint() function.

See also: eMinimumSizeHintMode for a detailed description

Definition at line 461 of file DockWidget.cpp.

void ads::CDockWidget::setTabToolTip ( const QString & text )

This is function sets text tooltip for title bar widget and tooltip for toggle view action

Definition at line 620 of file DockWidget.cpp.

void ads::CDockWidget::setTitleBarActions ( QList< QAction * > actions )

Set the actions that will be shown in the dock area title bar if this dock widget is the active tab. You should not add to many actions to the title bar, because this will remove the available space for the tabs. If you have a number of actions, just add an action with a menu to show a popup menu button in the title bar.

Definition at line 885 of file DockWidget.cpp.

void ads::CDockWidget::setToggleViewActionChecked ( bool Checked )

protected

This function changes the toggle view action without emitting any signal

Definition at line 256 of file DockWidget.cpp.

void ads::CDockWidget::setToggleViewActionMode ( eToggleViewActionMode Mode )

Configures the behavior of the toggle view action.

See also: eToggleViewActionMode for a detailed description

Definition at line 445 of file DockWidget.cpp.

void ads::CDockWidget::setToolBar ( QToolBar * ToolBar )

Assign a new tool bar that is shown above the content widget. The dock widget will become the owner of the tool bar and deletes it on destruction

Definition at line 676 of file DockWidget.cpp.

void ads::CDockWidget::setToolbarFloatingStyle ( bool topLevel )

privateslot

Adjusts the toolbar icon sizes according to the floating state

Definition at line 751 of file DockWidget.cpp.

void ads::CDockWidget::setToolBarIconSize	(	const QSize &	IconSize,
		eState	State
	)

This function sets the tool button icon size for the given state. If a dock widget is floating, there is more space an increasing the icon size is possible. For docked widgets, small icon sizes, eg. 16 x 16 might be better.

Definition at line 721 of file DockWidget.cpp.

void ads::CDockWidget::setToolBarStyle	(	Qt::ToolButtonStyle	Style,
		eState	State
	)

This function sets the tool button style for the given dock widget state. It is possible to switch the tool button style depending on the state. If a dock widget is floating, then here are more space and it is possible to select a style that requires more space like Qt::ToolButtonTextUnderIcon. For the docked state Qt::ToolButtonIconOnly might be better.

Definition at line 691 of file DockWidget.cpp.

void ads::CDockWidget::setWidget	(	QWidget *	widget,
		eInsertMode	InsertMode = `AutoScrollArea`
	)

Sets the widget for the dock widget to widget. The InsertMode defines how the widget is inserted into the dock widget. The content of a dock widget should be resizable do a very small size to prevent the dock widget from blocking the resizing. To ensure, that a dock widget can be resized very well, it is better to insert the content+ widget into a scroll area or to provide a widget that is already a scroll area or that contains a scroll area. If the InsertMode is AutoScrollArea, the DockWidget tries to automatically detect how to insert the given widget. If the widget is derived from QScrollArea (i.e. an QAbstractItemView), then the widget is inserted directly. If the given widget is not a scroll area, the widget will be inserted into a scroll area. To force insertion into a scroll area, you can also provide the InsertMode ForceScrollArea. To prevent insertion into a scroll area, you can provide the InsertMode ForceNoScrollArea

Definition at line 266 of file DockWidget.cpp.

void ads::CDockWidget::showFullScreen ( )

slot

Shows the widget in full-screen mode. Normally this function only affects windows. To make the interface compatible to QDockWidget, this function also maximizes a floating dock widget.

Note: Full-screen mode works fine under Windows, but has certain problems (doe not work) under X (Linux). These problems are due to limitations of the ICCCM protocol that specifies the communication between X11 clients and the window manager. ICCCM simply does not understand the concept of non-decorated full-screen windows.

Definition at line 899 of file DockWidget.cpp.

void ads::CDockWidget::showNormal ( )

slot

This function complements showFullScreen() to restore the widget after it has been in full screen mode.

Definition at line 913 of file DockWidget.cpp.

CDockWidgetTab * ads::CDockWidget::tabWidget ( ) const

Returns the tab widget of this dock widget that is shown in the dock area title bar

Definition at line 328 of file DockWidget.cpp.

QWidget * ads::CDockWidget::takeWidget ( )

Remove the widget from the dock and give ownership back to the caller

Definition at line 294 of file DockWidget.cpp.

QList< QAction * > ads::CDockWidget::titleBarActions ( ) const

virtual

Returns a list of actions that will be inserted into the dock area title bar if this dock widget becomes the current widget

Definition at line 892 of file DockWidget.cpp.

void ads::CDockWidget::titleChanged ( const QString & Title )

signal

This signal is emitted if the window title of this dock widget changed

void ads::CDockWidget::toggleView ( bool Open = true )

slot

This property controls whether the dock widget is open or closed. The toogleViewAction triggers this slot

Definition at line 475 of file DockWidget.cpp.

QAction * ads::CDockWidget::toggleViewAction ( ) const

Returns a checkable action that can be used to show or close this dock widget. The action's text is set to the dock widget's window title.

Definition at line 438 of file DockWidget.cpp.

void ads::CDockWidget::toggleViewInternal ( bool Open )

protected

Internal toggle view function that does not check if the widget already is in the given state

Definition at line 499 of file DockWidget.cpp.

QToolBar * ads::CDockWidget::toolBar ( ) const

This function returns the dock widget top tool bar. If no toolbar is assigned, this function returns nullptr. To get a vaild toolbar you either need to create a default empty toolbar via createDefaultToolBar() function or you need to assign your custom toolbar via setToolBar().

Definition at line 657 of file DockWidget.cpp.

QSize ads::CDockWidget::toolBarIconSize ( eState State ) const

Returns the icon size for a given docking state.

See also: setToolBarIconSize()

Definition at line 737 of file DockWidget.cpp.

Qt::ToolButtonStyle ads::CDockWidget::toolBarStyle ( eState State ) const

Returns the tool button style for the given docking state.

See also: setToolBarStyle()

Definition at line 707 of file DockWidget.cpp.

void ads::CDockWidget::topLevelChanged ( bool topLevel )

signal

This signal is emitted when the floating property changes. The topLevel parameter is true if the dock widget is now floating; otherwise it is false.

void ads::CDockWidget::viewToggled ( bool Open )

signal

This signal is emitted if the dock widget is opened or closed

void ads::CDockWidget::visibilityChanged ( bool visible )

signal

This signal is emitted when the dock widget becomes visible (or invisible). This happens when the widget is hidden or shown, as well as when it is docked in a tabbed dock area and its tab becomes selected or unselected.

QWidget * ads::CDockWidget::widget ( ) const

Returns the widget for the dock widget. This function returns zero if the widget has not been set.

Definition at line 321 of file DockWidget.cpp.