Added Config::setDropIndicatorAllowedFunc()

Changelog

@@ -3,6 +3,8 @@
  - Experimental support for docking into dock widgets which are in a MDI area.
  - Fixed potential crash involving infinite loop between QWidget::create() and QWidget::createWinId()
  - Moved DropIndicatorOverlayInterface::DropLocation enum to KDDockWidgets namespace scope
+ - Added Config::setDropIndicatorAllowedFunc() and corresponding example
+   (kddockwidgets_example --hide-certain-docking-indicators)
 
 * v1.5.1 (unreleased)
  - X11: Improved detecting which window is under the cursor, by using native X11 API

examples/dockwidgets/main.cpp

@@ -13,6 +13,7 @@
 #include "MyMainWindow.h"
 #include "MyFrameworkWidgetFactory.h"
 
+#include <algorithm>
 #include <kddockwidgets/Config.h>
 
 #include <QStyleFactory>
@@ -131,6 +132,10 @@ int main(int argc, char **argv)
                                       QCoreApplication::translate("main", "Allow switching tabs via context menu in tabs area"));
     parser.addOption(ctxtMenuOnTabs);
 
+    QCommandLineOption hideCertainDockingIndicators("hide-certain-docking-indicators",
+                                                     QCoreApplication::translate("main", "Illustrates usage of Config::setDropIndicatorAllowedFunc()"));
+    parser.addOption(hideCertainDockingIndicators);
+
 #if defined(DOCKS_DEVELOPER_MODE)
     parser.addOption(centralFrame);
 
@@ -253,6 +258,24 @@ int main(int argc, char **argv)
         return 1;
     }
 
+    if (parser.isSet(hideCertainDockingIndicators)) {
+        // Here we exemplify adding a restriction to "Dock Widget 8"
+        // Dock widget 8 will only be allowed to dock to the outter areasa
+        auto func = [](KDDockWidgets::DropLocation location,
+                       const KDDockWidgets::DockWidgetBase::List &source,
+                       const KDDockWidgets::DockWidgetBase::List &target) {
+            Q_UNUSED(target); // When dragging into a tab, 'target' would have the list of already tabbed dock widgets
+
+            const bool isDraggingDW8 = std::find_if(source.cbegin(), source.cend(), [] (KDDockWidgets::DockWidgetBase *dw) {
+                return dw->uniqueName() == QLatin1String("DockWidget #8");
+            }) != source.cend();
+
+            return (location & KDDockWidgets::DropLocation_Outter) || !isDraggingDW8;
+        };
+
+        KDDockWidgets::Config::self().setDropIndicatorAllowedFunc(func);
+    }
+
     KDDockWidgets::Config::self().setFlags(flags);
 
     const bool nonClosableDockWidget0 = parser.isSet(nonClosableDockWidget);

src/Config.cpp

@@ -54,6 +54,7 @@ public:
     DockWidgetFactoryFunc m_dockWidgetFactoryFunc = nullptr;
     MainWindowFactoryFunc m_mainWindowFactoryFunc = nullptr;
     TabbingAllowedFunc m_tabbingAllowedFunc = nullptr;
+    DropIndicatorAllowedFunc m_dropIndicatorAllowedFunc = nullptr;
     FrameworkWidgetFactory *m_frameworkWidgetFactory = nullptr;
     Flags m_flags = Flag_Default;
     InternalFlags m_internalFlags = InternalFlag_None;
@@ -180,6 +181,16 @@ TabbingAllowedFunc Config::tabbingAllowedFunc() const
     return d->m_tabbingAllowedFunc;
 }
 
+void Config::setDropIndicatorAllowedFunc(DropIndicatorAllowedFunc func)
+{
+    d->m_dropIndicatorAllowedFunc = func;
+}
+
+DropIndicatorAllowedFunc Config::dropIndicatorAllowedFunc() const
+{
+    return d->m_dropIndicatorAllowedFunc;
+}
+
 void Config::setAbsoluteWidgetMinSize(QSize size)
 {
     if (!DockRegistry::self()->isEmpty(/*excludeBeingDeleted=*/false)) {

src/Config.h

@@ -20,6 +20,7 @@
 #define KD_DOCKWIDGETS_CONFIG_H
 
 #include "docks_export.h"
+#include "KDDockWidgets.h"
 
 #include <qglobal.h>
 
@@ -37,6 +38,22 @@ class FrameworkWidgetFactory;
 typedef KDDockWidgets::DockWidgetBase *(*DockWidgetFactoryFunc)(const QString &name);
 typedef KDDockWidgets::MainWindowBase *(*MainWindowFactoryFunc)(const QString &name);
 
+/// @brief Function to allow more granularity to disallow where widgets are dropped
+///
+/// By default, widgets can be dropped to the outter and inner left/right/top/bottom
+/// and center. The client app can however provide a lambda via setDropIndicatorAllowedFunc
+/// to block (by returning false) any specific locations they desire.
+///
+/// @param location The drop indicator location to allow or disallow
+/// @param source The dock widgets being dragged
+/// @param target The dock widgets within an existing docked tab group
+/// @return true if the docking is allowed.
+/// @sa setDropIndicatorAllowedFunc
+typedef bool (*DropIndicatorAllowedFunc)(DropLocation location,
+                                         const QVector<DockWidgetBase *> &source,
+                                         const QVector<DockWidgetBase *> &target);
+
+/// @deprecated Use DropIndicatorAllowedFunc instead.
 /// @brief Function to allow the user more granularity to disallow dock widgets to tab together
 /// @param source The dock widgets being dragged
 /// @param target The dock widgets within an existing docked tab group
@@ -203,6 +220,8 @@ public:
     bool dropIndicatorsInhibited() const;
 
     /**
+     * @deprecated Use setDropIndicatorAllowedFunc() instead, and catch the DropLocation_Center case.
+     *
      * @brief 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 @p func. If
@@ -219,8 +238,10 @@ public:
      *    // disallows dockFoo to be tabbed with dockBar.
      *    return !(source.contains(dockFoo) && target.contains(dockBar));
      * }
-     * @endcode
+     *
      * KDDockWidgets::Config::self()->setTabbingAllowedFunc(func);
+     *
+     * @endcode
      */
     void setTabbingAllowedFunc(TabbingAllowedFunc func);
 
@@ -229,6 +250,37 @@ public:
     ///@sa setTabbingAllowedFunc().
     TabbingAllowedFunc tabbingAllowedFunc() const;
 
+    /**
+     * @brief Allows the client app to disallow certain docking indicators.
+     *
+     * For example, let's assume the app doesn't want to show outter indicators for a certain
+     * dock widget.
+     *
+     * @code
+     * #include <kddockwidgets/Config.h>
+     * (...)
+     *
+     * auto func = [] (KDDockWidgets::DropLocation loc,
+     *                 const KDDockWidgets::DockWidgetBase::List &source,
+     *                 const KDDockWidgets::DockWidgetBase::List &target)
+     * {
+     *    // disallows dockFoo to be docked to outter areas
+     *    return !((loc & KDDockWidgets::DropLocation_Outter) && source.contains(dockFoo));
+     * }
+     *
+     * KDDockWidgets::Config::self()->setDropIndicatorAllowedFunc(func);
+     *
+     * @endcode
+     *
+     * Run "kddockwidgets_example --hide-certain-docking-indicators" to see this in action.
+     */
+    void setDropIndicatorAllowedFunc(DropIndicatorAllowedFunc func);
+
+    ///@brief Used internally by the framework. Returns the function which was passed to setDropIndicatorAllowedFunc()
+    ///By default it's nullptr.
+    ///@sa setDropIndicatorAllowedFunc().
+    DropIndicatorAllowedFunc dropIndicatorAllowedFunc() const;
+
     ///@brief 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.

src/private/DropIndicatorOverlayInterface.cpp

@@ -160,6 +160,11 @@ bool DropIndicatorOverlayInterface::dropIndicatorVisible(DropLocation dropLoc) c
         return false;
     }
 
+    if (auto dropIndicatorAllowedFunc = Config::self().dropIndicatorAllowedFunc()) {
+        if (!dropIndicatorAllowedFunc(dropLoc, source, target))
+            return false;
+    }
+
     return true;
 }