KDDockWidgets::Config Class Reference

Singleton to allow to choose certain behaviours of the framework. More...

#include <Config.h>

Public Types
enum	CustomizableWidget {   CustomizableWidget_None = 0, CustomizableWidget_TitleBar, CustomizableWidget_DockWidget, CustomizableWidget_Frame,   CustomizableWidget_TabBar, CustomizableWidget_TabWidget, CustomizableWidget_FloatingWindow, CustomizableWidget_Separator }
	List of customizable widgets. More...
enum	Flag {   Flag_None = 0, Flag_NativeTitleBar = 1, Flag_AeroSnapWithClientDecos = 2, Flag_AlwaysTitleBarWhenFloating = 4,   Flag_HideTitleBarWhenTabsVisible = 8, Flag_AlwaysShowTabs = 16, Flag_AllowReorderTabs = 32, Flag_TabsHaveCloseButton = 64,   Flag_DoubleClickMaximizes = 128, Flag_TitleBarHasMaximizeButton = 256, Flag_TitleBarIsFocusable = 512, Flag_LazyResize = 1024,   Flag_DontUseUtilityFloatingWindows = 0x1000, Flag_TitleBarHasMinimizeButton = 0x2000 | Flag_DontUseUtilityFloatingWindows, Flag_TitleBarNoFloatButton = 0x4000, Flag_AutoHideSupport = 0x8000 | Flag_TitleBarNoFloatButton,   Flag_KeepAboveIfNotUtilityWindow = 0x10000, Flag_CloseOnlyCurrentTab = 0x20000, Flag_ShowButtonsOnTabBarIfTitleBarHidden = 0x40000, Flag_AllowSwitchingTabsViaMenu = 0x80000,   Flag_Default = Flag_AeroSnapWithClientDecos }
	Flag enum to tune certain behaviours, the defaults are Flag_Default. More...
enum	InternalFlag {   InternalFlag_None = 0, InternalFlag_NoAeroSnap = 1, InternalFlag_DontUseParentForFloatingWindows = 2, InternalFlag_DontUseQtToolWindowsForFloatingWindows = 4,   InternalFlag_DontShowWhenUnfloatingHiddenWindow = 8, InternalFlag_UseTransparentFloatingWindow = 16, InternalFlag_DisableTranslucency = 32, InternalFlag_TopLevelIndicatorRubberBand = 64 }

Public Member Functions
	~Config ()
	destructor, called at shutdown More...
QSize	absoluteWidgetMaxSize () const
QSize	absoluteWidgetMinSize () const
Config::CustomizableWidgets	disabledPaintEvents () const
DockWidgetFactoryFunc	dockWidgetFactoryFunc () const
	Returns the DockWidgetFactoryFunc. nullptr by default. More...
qreal	draggedWindowOpacity () const
	returns the opacity to use when dragging dock widgets By default it's 1.0, fully opaque More...
DropIndicatorAllowedFunc	dropIndicatorAllowedFunc () const
	Used internally by the framework. Returns the function which was passed to setDropIndicatorAllowedFunc() By default it's nullptr. More...
bool	dropIndicatorsInhibited () const
	Returns whether drop indicators are inhibited. by default this is false unless you call setDropIndicatorsInhibited(true) More...
Flags	flags () const
	returns the chosen flags More...
FrameworkWidgetFactory *	frameworkWidgetFactory () const
	getter for the framework widget factory More...
InternalFlags	internalFlags () const
MainWindowFactoryFunc	mainWindowFactoryFunc () const
	Returns the MainWindowFactoryFunc. nullptr by default. More...
int	mdiPopupThreshold () const
int	separatorThickness () const
	Returns the thickness of the separator. More...
void	setAbsoluteWidgetMaxSize (QSize size)
	Sets the maximum size a dock widget can have. Widgets can still provide their own max-size and it will be respected, however it can never be bigger than this one. More...
void	setAbsoluteWidgetMinSize (QSize size)
	Sets the minimum size a dock widget can have. Widgets can still provide their own min-size and it will be respected, however it can never be smaller than this one. More...
void	setDisabledPaintEvents (CustomizableWidgets)
	Disables our internal widget's paint events By default, KDDockWidget's internal widgets reimplement paintEvent(). Disabling them (which makes the base-class, QWidget::paintEvent() be called instead) can be useful if you want to style. More...
void	setDockWidgetFactoryFunc (DockWidgetFactoryFunc)
	Registers a DockWidgetFactoryFunc. More...
void	setDraggedWindowOpacity (qreal opacity)
	sets the dragged window opacity 1.0 is fully opaque while 0.0 is fully transparent More...
void	setDropIndicatorAllowedFunc (DropIndicatorAllowedFunc func)
	Allows the client app to disallow certain docking indicators. More...
void	setDropIndicatorsInhibited (bool inhibit) const
	Allows to disable support for drop indicators while dragging By default drop indicators will be shown when dragging dock widgets. This functionality can be toggled whenever you need it (it's not a startup-only setting). More...
void	setFlags (Flags flags)
	setter for the flags More...
void	setFrameworkWidgetFactory (FrameworkWidgetFactory *)
	Sets the WidgetFactory. More...
void	setInternalFlags (InternalFlags flags)
void	setMainWindowFactoryFunc (MainWindowFactoryFunc)
	counter-part of DockWidgetFactoryFunc but for the main window. Should be rarely used. It's good practice to have the main window before restoring a layout. It's here so we can use it in the linter executable More...
void	setMDIPopupThreshold (int)
	Sets the MDI popup threshold. When the layout is MDI and you drag a dock widget X pixels behond the window's edge, it will float the dock widget. by default this value is 250px. Use -1 to disable. More...
void	setSeparatorThickness (int value)
	setter for separatorThickness Note: Only use this function at startup before creating any DockWidget or MainWindow. More...
void	setTabbingAllowedFunc (TabbingAllowedFunc func)
	Allows the user to intercept a docking attempt to center (tabbed) and disallow it. More...
TabbingAllowedFunc	tabbingAllowedFunc () const
	Used internally by the framework. Returns the function which was passed to setTabbingAllowedFunc() By default it's nullptr. More...

Static Public Member Functions
static Config &	self ()
	returns the singleton Config instance More...

Detailed Description

Singleton to allow to choose certain behaviours of the framework.

The setters should only be used before creating any DockWidget or MainWindow, preferably right after creating the QApplication.

Definition at line 74 of file Config.h.

Member Enumeration Documentation

CustomizableWidget

enum KDDockWidgets::Config::CustomizableWidget

List of customizable widgets.

Enumerator
CustomizableWidget_None	None.
CustomizableWidget_TitleBar	The title bar.
CustomizableWidget_DockWidget	The dock widget.
CustomizableWidget_Frame	The container for a group of 1 or more dockwidgets which are tabbed together.
CustomizableWidget_TabBar	The tab bar, child of Frame, which contains 1 or more dock widgets.
CustomizableWidget_TabWidget	The tab widget which relates to the tab bar.
CustomizableWidget_FloatingWindow	A top-level window. The container for 1 or more Frame nested side by side.
CustomizableWidget_Separator	The draggable separator between dock widgets in a layout.

Definition at line 114 of file Config.h.

Flag

enum KDDockWidgets::Config::Flag

Flag enum to tune certain behaviours, the defaults are Flag_Default.

Warning

Only the default is supported on all platforms. Not all options work with all window managers, Qt does its best to abstract the differences however that's only a best effort. This is true specially for any option that changes window flags.

Enumerator
Flag_None	No option set.
Flag_NativeTitleBar	Enables the Native OS title bar on OSes that support it (Windows 10, macOS), ignored otherwise.
Flag_AeroSnapWithClientDecos	Deprecated. This is now default and cannot be turned off. Moving a window on Windows 10 uses native moving, as that works well across screens with different HDPI settings. There's no reason to use manual client/Qt window moving.
Flag_AlwaysTitleBarWhenFloating	Floating windows will have a title bar even if Flag_HideTitleBarWhenTabsVisible is specified. Unneeded if Flag_HideTitleBarWhenTabsVisible isn't specified, as that's the default already.
Flag_HideTitleBarWhenTabsVisible	Hides the title bar if there's tabs visible. The empty space in the tab bar becomes draggable.
Flag_AlwaysShowTabs	Always show tabs, even if there's only one,.
Flag_AllowReorderTabs	Allows user to re-order tabs by dragging them.
Flag_TabsHaveCloseButton	Tabs will have a close button. Equivalent to QTabWidget::setTabsClosable(true).
Flag_DoubleClickMaximizes	Double clicking the titlebar will maximize a floating window instead of re-docking it.
Flag_TitleBarHasMaximizeButton	The title bar will have a maximize/restore button when floating. This is mutually-exclusive with the floating button (since many apps behave that way).
Flag_TitleBarIsFocusable	You can click the title bar and it will focus the last focused widget in the focus scope. If no previously focused widget then it focuses the user's dock widget guest, which should accept focus or use a focus proxy.
Flag_LazyResize	The dock widgets are resized in a lazy manner. The actual resize only happens when you release the mouse button.
Flag_DontUseUtilityFloatingWindows
Flag_TitleBarHasMinimizeButton	The title bar will have a minimize button when floating. This implies Flag_DontUseUtilityFloatingWindows too, otherwise they wouldn't appear in the task bar.
Flag_TitleBarNoFloatButton	The TitleBar won't show the float button.
Flag_AutoHideSupport	Supports minimizing dock widgets to the side-bar. By default it also turns off the float button, but you can remove Flag_TitleBarNoFloatButton to have both.
Flag_KeepAboveIfNotUtilityWindow	Only meaningful if Flag_DontUseUtilityFloatingWindows is set. If floating windows are normal windows, you might still want them to keep above and not minimize when you focus the main window.
Flag_CloseOnlyCurrentTab	The TitleBar's close button will only close the current tab, instead of all of them.
Flag_ShowButtonsOnTabBarIfTitleBarHidden	When using Flag_HideTitleBarWhenTabsVisible the close/float buttons disappear with the title bar. With Flag_ShowButtonsOnTabBarIfHidden they'll be shown in the tab bar.
Flag_AllowSwitchingTabsViaMenu	Allow switching tabs via a context menu when right clicking on the tab area.
Flag_Default	The defaults.

Definition at line 87 of file Config.h.

InternalFlag

enum KDDockWidgets::Config::InternalFlag

Enumerator
InternalFlag_None	The default.
InternalFlag_NoAeroSnap	Only for development. Disables Aero-snap.
InternalFlag_DontUseParentForFloatingWindows	FloatingWindows won't have a parent top-level.
InternalFlag_DontUseQtToolWindowsForFloatingWindows	FloatingWindows will use Qt::Window instead of Qt::Tool.
InternalFlag_DontShowWhenUnfloatingHiddenWindow	DockWidget::setFloating(false) won't do anything if the window is hidden.
InternalFlag_UseTransparentFloatingWindow	For QtQuick only. Allows to have round-corners. It's flaky when used with native Windows drop-shadow.
InternalFlag_DisableTranslucency	KDDW tries to detect if your Window Manager doesn't support transparent windows, but the detection might fail
InternalFlag_TopLevelIndicatorRubberBand	with more exotic setups. This flag can be used to override. Makes the rubber band of classic drop indicators to be top-level windows. Helps with working around MFC bugs

Definition at line 129 of file Config.h.

Constructor & Destructor Documentation

~Config()

KDDockWidgets::Config::~Config

(

)

destructor, called at shutdown

Definition at line 90 of file Config.cpp.

Member Function Documentation

absoluteWidgetMaxSize()

QSize KDDockWidgets::Config::absoluteWidgetMaxSize

(

)

const

Definition at line 220 of file Config.cpp.

absoluteWidgetMinSize()

QSize KDDockWidgets::Config::absoluteWidgetMinSize

(

)

const

Definition at line 205 of file Config.cpp.

disabledPaintEvents()

Config::CustomizableWidgets KDDockWidgets::Config::disabledPaintEvents

(

)

const

Definition at line 331 of file Config.cpp.

dockWidgetFactoryFunc()

DockWidgetFactoryFunc KDDockWidgets::Config::dockWidgetFactoryFunc

(

)

const

Returns the DockWidgetFactoryFunc. nullptr by default.

Definition at line 123 of file Config.cpp.

draggedWindowOpacity()

qreal KDDockWidgets::Config::draggedWindowOpacity

(

)

const

returns the opacity to use when dragging dock widgets By default it's 1.0, fully opaque

Definition at line 170 of file Config.cpp.

dropIndicatorAllowedFunc()

DropIndicatorAllowedFunc KDDockWidgets::Config::dropIndicatorAllowedFunc

(

)

const

Used internally by the framework. Returns the function which was passed to setDropIndicatorAllowedFunc() By default it's nullptr.

See also

setDropIndicatorAllowedFunc().

Definition at line 190 of file Config.cpp.

dropIndicatorsInhibited()

bool KDDockWidgets::Config::dropIndicatorsInhibited

(

)

const

Returns whether drop indicators are inhibited. by default this is false unless you call setDropIndicatorsInhibited(true)

Definition at line 354 of file Config.cpp.

flags()

Config::Flags KDDockWidgets::Config::flags

(

)

const

returns the chosen flags

Definition at line 95 of file Config.cpp.

Referenced by setInternalFlags().

frameworkWidgetFactory()

FrameworkWidgetFactory * KDDockWidgets::Config::frameworkWidgetFactory

(

)

const

getter for the framework widget factory

Definition at line 145 of file Config.cpp.

Referenced by KDDockWidgets::MainWindowBase::overlayOnSideBar(), and KDDockWidgets::LayoutSaver::restoreLayout().

internalFlags()

Config::InternalFlags KDDockWidgets::Config::internalFlags

(

)

const

Definition at line 225 of file Config.cpp.

mainWindowFactoryFunc()

MainWindowFactoryFunc KDDockWidgets::Config::mainWindowFactoryFunc

(

)

const

Returns the MainWindowFactoryFunc. nullptr by default.

Definition at line 133 of file Config.cpp.

mdiPopupThreshold()

int KDDockWidgets::Config::mdiPopupThreshold

(

)

const

Definition at line 341 of file Config.cpp.

self()

Config & KDDockWidgets::Config::self ( )

static

returns the singleton Config instance

Definition at line 84 of file Config.cpp.

Referenced by KDDockWidgets::RubberBandQuick::RubberBandQuick(), KDDockWidgets::actualOptions(), actualParent(), hackFindParentHarder(), lint(), KDDockWidgets::MainWindowBase::overlayOnSideBar(), Layouting::SeparatorWidget::paintEvent(), KDDockWidgets::LayoutSaver::restoreLayout(), KDDockWidgets::DockWidgetBase::setFloating(), and windowFlagsToUse().

separatorThickness()

int KDDockWidgets::Config::separatorThickness

(

)

const

Returns the thickness of the separator.

Default is 5px.

Definition at line 150 of file Config.cpp.

References Layouting::Config::self(), and Layouting::Config::separatorThickness().

setAbsoluteWidgetMaxSize()

void KDDockWidgets::Config::setAbsoluteWidgetMaxSize

(

QSize

size

)

Sets the maximum size a dock widget can have. Widgets can still provide their own max-size and it will be respected, however it can never be bigger than this one.

Definition at line 210 of file Config.cpp.

setAbsoluteWidgetMinSize()

void KDDockWidgets::Config::setAbsoluteWidgetMinSize

(

QSize

size

)

Sets the minimum size a dock widget can have. Widgets can still provide their own min-size and it will be respected, however it can never be smaller than this one.

Definition at line 195 of file Config.cpp.

setDisabledPaintEvents()

void KDDockWidgets::Config::setDisabledPaintEvents

(

CustomizableWidgets

widgets

)

Disables our internal widget's paint events By default, KDDockWidget's internal widgets reimplement paintEvent(). Disabling them (which makes the base-class, QWidget::paintEvent() be called instead) can be useful if you want to style.

Definition at line 326 of file Config.cpp.

setDockWidgetFactoryFunc()

void KDDockWidgets::Config::setDockWidgetFactoryFunc

(

DockWidgetFactoryFunc

func

)

Registers a DockWidgetFactoryFunc.

This is optional, the default is nullptr.

A DockWidgetFactoryFunc is a function that receives a dock widget name and returns a DockWidget instance.

While restoring, LayoutSaver requires all dock widgets to exist. If a DockWidget doesn't exist then a DockWidgetFactoryFunc function is required, so the layout saver can ask to create the DockWidget and then restore it.

Definition at line 118 of file Config.cpp.

Referenced by lint().

setDraggedWindowOpacity()

void KDDockWidgets::Config::setDraggedWindowOpacity

(

qreal

opacity

)

sets the dragged window opacity 1.0 is fully opaque while 0.0 is fully transparent

Definition at line 165 of file Config.cpp.

setDropIndicatorAllowedFunc()

void KDDockWidgets::Config::setDropIndicatorAllowedFunc

(

DropIndicatorAllowedFunc

func

)

Allows the client app to disallow certain docking indicators.

For example, let's assume the app doesn't want to show outer indicators for a certain dock widget.

#include <kddockwidgets/Config.h>
(...)
 
auto func = [] (KDDockWidgets::DropLocation loc,
                const KDDockWidgets::DockWidgetBase::List &source,
                const KDDockWidgets::DockWidgetBase::List &target,
                KDDockWidgets::DropArea *)
{
   // disallows dockFoo to be docked to outer areas
   return !((loc & KDDockWidgets::DropLocation_Outter) && source.contains(dockFoo));
};
 
KDDockWidgets::Config::self().setDropIndicatorAllowedFunc(func);

Run "kddockwidgets_example --hide-certain-docking-indicators" to see this in action.

Definition at line 185 of file Config.cpp.

setDropIndicatorsInhibited()

void KDDockWidgets::Config::setDropIndicatorsInhibited

(

bool

inhibit

)

const

Allows to disable support for drop indicators while dragging By default drop indicators will be shown when dragging dock widgets. This functionality can be toggled whenever you need it (it's not a startup-only setting).

Definition at line 346 of file Config.cpp.

setFlags()

void KDDockWidgets::Config::setFlags

(

Flags

flags

)

setter for the flags

Parameters

flags

the flags to set Not all flags are guaranteed to be set, as the OS might not supported them Call flags() after the setter if you need to know what was really set

Definition at line 100 of file Config.cpp.

References Flag_LazyResize, Layouting::Config::flags(), Layouting::Config::LazyResize, Layouting::Config::self(), and Layouting::Config::setFlags().

setFrameworkWidgetFactory()

void KDDockWidgets::Config::setFrameworkWidgetFactory

(

FrameworkWidgetFactory *

wf

)

Sets the WidgetFactory.

By default DefaultWidgetFactory is used, which gives you FrameWidget, TitleBarWidget, TabBarWidget, TabWidgetWidget etc. You can set your own factory, to supply your own variants of those classes, for the purposes of changing GUI appearance and such.

Also potentially useful to return QtQuick classes instead of the QtWidget based ones. Ownership is taken.

Definition at line 138 of file Config.cpp.

setInternalFlags()

void KDDockWidgets::Config::setInternalFlags

(

InternalFlags

flags

)

Definition at line 230 of file Config.cpp.

References flags().

setMainWindowFactoryFunc()

void KDDockWidgets::Config::setMainWindowFactoryFunc

(

MainWindowFactoryFunc

func

)

counter-part of DockWidgetFactoryFunc but for the main window. Should be rarely used. It's good practice to have the main window before restoring a layout. It's here so we can use it in the linter executable

Definition at line 128 of file Config.cpp.

Referenced by lint().

setMDIPopupThreshold()

void KDDockWidgets::Config::setMDIPopupThreshold

(

int

threshold

)

Sets the MDI popup threshold. When the layout is MDI and you drag a dock widget X pixels behond the window's edge, it will float the dock widget. by default this value is 250px. Use -1 to disable.

Definition at line 336 of file Config.cpp.

setSeparatorThickness()

void KDDockWidgets::Config::setSeparatorThickness

(

int

value

)

setter for separatorThickness Note: Only use this function at startup before creating any DockWidget or MainWindow.

Definition at line 155 of file Config.cpp.

References Layouting::Config::self(), and Layouting::Config::setSeparatorThickness().

setTabbingAllowedFunc()

void KDDockWidgets::Config::setTabbingAllowedFunc

(

TabbingAllowedFunc

func

)

Allows the user to intercept a docking attempt to center (tabbed) and disallow it.

Deprecated:

Use setDropIndicatorAllowedFunc() instead, and catch the DropLocation_Center case.

Whenever the user tries to tab two widgets together, the framework will call func. If it returns true, then tabbing is allowed, otherwise not.

Example:

#include <kddockwidgets/Config.h>
(...)
 
auto func = [] (const KDDockWidgets::DockWidgetBase::List &source,
                const KDDockWidgets::DockWidgetBase::List &target)
{
   // disallows dockFoo to be tabbed with dockBar.
   return !(source.contains(dockFoo) && target.contains(dockBar));
};
 
KDDockWidgets::Config::self().setTabbingAllowedFunc(func);

Definition at line 175 of file Config.cpp.

tabbingAllowedFunc()

TabbingAllowedFunc KDDockWidgets::Config::tabbingAllowedFunc

(

)

const

Used internally by the framework. Returns the function which was passed to setTabbingAllowedFunc() By default it's nullptr.

See also

setTabbingAllowedFunc().

Definition at line 180 of file Config.cpp.

---

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

• Config.h
• Config.cpp