KDDockWidgets API Documentation  1.1.1
Public Types | Public Member Functions | Static Public Member Functions | List of all members
KDDockWidgets::Config Class Reference

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

#include <Config.h>

Public Types

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_internal_DontUseQtToolWindowsForFloatingWindows = 0x800, Flag_internal_DontUseParentForFloatingWindows = 0x1000, Flag_DontUseUtilityFloatingWindows = Flag_internal_DontUseQtToolWindowsForFloatingWindows | Flag_internal_DontUseParentForFloatingWindows, Flag_TitleBarHasMinimizeButton = 0x2000 | Flag_DontUseUtilityFloatingWindows,
  Flag_TitleBarNoFloatButton = 0x4000, Flag_AutoHideSupport = 0x8000 | Flag_TitleBarNoFloatButton, Flag_Default = Flag_AeroSnapWithClientDecos
}
 Flag enum to tune certain behaviours, the defaults are Flag_Default. More...
 

Public Member Functions

 ~Config ()
 destructor, called at shutdown
 
DockWidgetFactoryFunc dockWidgetFactoryFunc () const
 Returns the DockWidgetFactoryFunc. nullptr by default.
 
qreal draggedWindowOpacity () const
 returns the opacity to use when dragging dock widgets By default it's 1.0, fully opaque
 
Flags flags () const
 returns the chosen flags
 
FrameworkWidgetFactoryframeworkWidgetFactory () const
 getter for the framework widget factory
 
MainWindowFactoryFunc mainWindowFactoryFunc () const
 Returns the MainWindowFactoryFunc. nullptr by default.
 
QQmlEngine * qmlEngine () const
 
int separatorThickness () const
 Returns the thickness of the separator. 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
 
void setFlags (Flags flags)
 setter for the flags More...
 
void setFrameworkWidgetFactory (FrameworkWidgetFactory *)
 Sets the WidgetFactory. More...
 
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
 
void setQmlEngine (QQmlEngine *)
 Sets the QQmlEngine to use. Applicable only when using QtQuick.
 
void setSeparatorThickness (int value)
 setter for separatorThickness Note: Only use this function at startup before creating any DockWidget or MainWindow.
 
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 Configself ()
 returns the singleton Config instance
 

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.

Member Enumeration Documentation

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

Enumerator
Flag_None 

No option set.

Flag_NativeTitleBar 

Enables the Native OS title bar on OSes that support it (Windows 10, macOS), ignored otherwise. This is mutually exclusive with Flag_AeroSnap.

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_internal_DontUseQtToolWindowsForFloatingWindows 

FloatingWindows will use Qt::Window instead of Qt::Tool. Internal, use Flag_DontUseUtilityFloatingWindows instead.

Flag_internal_DontUseParentForFloatingWindows 

FloatingWindows won't have a parent top-level. Internal, use Flag_DontUseUtilityFloatingWindows instead.

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_Default 

The defaults.

Member Function Documentation

int KDDockWidgets::Config::separatorThickness ( ) const

Returns the thickness of the separator.

Default is 5px.

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.

void KDDockWidgets::Config::setFlags ( Flags  flags)

setter for the flags

Parameters
flagsthe 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
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.

void KDDockWidgets::Config::setTabbingAllowedFunc ( TabbingAllowedFunc  func)

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

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,
{
// disallows dockFoo to be tabbed with dockBar.
return !(source.contains(dockFoo) && target.contains(dockBar));
}

KDDockWidgets::Config::self()->setTabbingAllowedFunc(func);

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().

Klarälvdalens Datakonsult AB (KDAB)
"The Qt, C++ and OpenGL Experts"
https://www.kdab.com/
KDDockWidgets
Advanced Dock Widget Framework for Qt
https://www.kdab.com/development-resources/qt-tools/kddockwidgets/