Extend FLTK with a cross-platform way to undock and dock widget groups #1257

Hey! Currently I only have access to a X desktop, so I tested on that. Everything seems to be in order.

If I understand correctly, you're aiming for something slightly different than is achieved using my or Gonzalo's implementation (still, they vary a great deal).

I've got a couple of questions:

1. For my implementation, the biggest inspiration is wxAUI, and I still have a thing or two to "learn" from it. What existing docking system inspired yours? (I'm not familiar at all with anything GTK, so I may be missing an obvious connection).
2. Why isn't it using Wayland subsurfaces as a stand in for xdg_toplevel_drag? In my testing this has no real problems bar one - popup menus initiated in detached windows need to intersect with the main window, even if that means they aren't anywhere close to the detached window.
3. Can external code such as my docking implementation make use of xdg_toplevel_drag handling in your proposal?

As for your question, I don't think it can be answered yes/no because there is a lot of ways to define the problem of docking. For one, my docking is so different that it either wouldn't work as replacement for the other even with major modifications.

I tried it. Its API is really clean, but man, you have your work cut out for you if you want to make it generic! Here are my comments:

1. There appears to be a bug when docking/undocking in Fl_Tabs 2. The selected tab is automatically switched on undocking.
2. Is there a way to automatically hide the target_box() when there are no elements and have it appear once the dockable item is moved close to it?
3. Right now, docking seems to resize the dockable element into the docking target. Is there a way to keep it the same size? Does docking pay attention to the resizable flag of the docking item?
4. Is there a way to dock two groups into the docking target (packing them side by side or top to bottom), assuming they fit the target size?
5. There should be a way to, optionally, serialize the docking layout to disk on a per application basis, so that the application opens with the same layout each time. In mrv2, I used .ini files as it was application specific, but a more generic approach might need to use xml (rapidxml which is a single .hpp file) or json (nlohmann-json) which is the most readable format. Qt6 and Windows' MSVC Dev studio support this.

@ManoloFLTK Thanks for this proposal. I didn't have much time to test, but my basic feeling is that it's a nice and useful feature. I ran your test program and it was a positive experience, but it also revealed (to me at least) something similar to @ggarra13's arguments. In short: I'd wish more flexibility, but this is only a first impression. Please don't get me wrong, I think it's a great start.

I'm writing this some days after my tests, w/o actually looking at the code, which isn't that important for getting a feeling about the issue.

Let's start with the group that is to be dragged and docked elsewhere. I understand that it needs a kind of handle to be dragged around, that's fine. The only thing I don't understand is its name in the implementation: why is it called "command" box? It could be drag_box or something similar, or did I miss anything? What "commands" is it good for? I didn't check nor test this: could this box be invisible, i.e. a box with box(FL_NO_BOX)? User documentation would then have to specify where a particular group could be accessed for dragging etc..

The more important part is the receiving group. The documentation says: when a draggable group is dragged to a target box "it takes the size of its receiving 'target box'". This seems to be too restrictive, particularly because the receiving group has to reserve space for the draggable box - which is IMHO counter-intuitive.

I imagine that any Fl_Group could be a receiving group, for instance an Fl_Flex or Fl_Grid (if enabled by calling a specific method and adding a target box). Fl_Flex would be much simpler, so let's think about this kind of group first. The Fl_Flex could have to include a "target_box", this would be OK. It could, for instance, be a very small box at the end of the Fl_Flex. When a dragged group is released over this target box, there should be a callback or maybe a virtual method that's called so the Fl_Flex can arrange its children or reject the addition. Perhaps the dragged group could also be inserted at any position, not only as the last child. Maybe it could just be added to the group (Fl_Flex), and its on_insert() method would arrange the new order and sizes. After that the target box could still receive another Fl_Draggable_Group which @ggarra13 asked for (multiple groups can be dropped to the same target group).

Fl_Grid would be much more complicated, because the new group would have to be inserted at a specific grid position, but that might be doable as well. Maybe the (invisible) target box could occlude the entire Fl_Grid and when receiving a "request" to drop another group it would have to determine the column and row of the grid and set more attributes which would only be doable in the context of the Fl_Grid.

An Fl_Tabs widget (or a subclass) could decide itself if the new dragged group would create a new tab or be inserted into an existing one. Again, only the Fl_Tabs widget (subclass) could decide what to do. Possibly a new tab when dropped over the tabs or inserted into one of the tabs if that is able to receive a dragged group.

Sorry for being so vague, I'm just thinking about the problem of dragging groups and inserting them anywhere in an existing GUI. The main new feature would be that a receiving group would resize its existing and the new widget itself w/o having to keep a reserved space. I don't have a real proposal how to implement this, it's just from the view of a "user". I hope this helps anyway.

Proposal to add support of docking/undocking in FLTK with a new widget Fl_Dockable_Group - version 2

Get, build, and run the complete proposal with:

git clone https://github.com/ManoloFLTK/fltk  fltk-dock
cd fltk-dock
git checkout dock-undock
mkdir build
cd build
cmake ..
make dock_undock
bin/test/dock_undock

Extending FLTK with support of docking/undocking is especially important for its Wayland backend because Wayland prohibits the implementation of a docking mechanism without extending FLTK. The reason is that, under Wayland, a window is not aware of its location within the display, and even less of its location relatively to that of other windows, a key information for the docking operation. Wayland has been recently extended with a new protocol "XDG toplevel drag" whose aim is:

This allows having detachable parts of a window that when dragged out of it become a new window and can be dragged over an existing window to be reattached".

That's exactly undocking/docking support. Therefore, docking requires the Wayland backend of FLTK to be extended to support this new protocol. Furthermore, Wayland implements docking as a variation of the drag-and-drop mechanism, which is very different from how other platforms see a docking operation. A new FLTK class provides the opportunity to completely hide the differences between how docking works under the various platforms.

The new Fl_Dockable_Group class derives from Fl_Group and as such can contain any widget collection. Two notions embody the functioning of this class.

• A "drag widget" is a child of the dockable object where clicking and dragging detaches the dockable from its current parent and transforms it into a draggable, functioning, Fl_Window. A dockable's "drag widget" is most often an Fl_Box but the Fl_Dockable_Group API supports any child Fl_Widget with any features to be a dockable's "drag widget".
• A "docking target widget" belongs to an Fl_Widget-derived class, and most often to an Fl_Group-derived class that represents in the GUI a location where a dockable could dock. A "docking target widget" defines a "docking area", a region of the target widget where dragging a dockable and releasing the mouse results in docking. A widget class must implement its handle(int) method and its destructor following specified instructions to become a "docking target widget" and therefore a potential docking location in the GUI.

FLTK defines only a very basic "docking target widget", class Fl_Dockable_Group::Docking_Target_Box, that is an Fl_Box which can receive and dock dockables and can let them be undocked and dragged away. Any other desired behavior for a docking target widget is application-defined.

A "drag widget" and its parent Fl_Dockable_Group alternate between 3 states during their lifetime

1. UNDOCK: the dockable is docked somewhere and can be undocked and dragged away with the mouse.
2. DRAG: the dockable is in a toplevel Fl_Window that can be moved with the mouse to some location of interest and that is also functional and event-responsive as such.
3. DOCK: the dockable has been moved above (an area of interest of) an FLTK widget and would dock in that part of the GUI if the mouse would be released.

FLTK changes the label and the background color of the "drag widget" when its state changes using values that can be freely set by the FLTK app.

A "docking target widget" can be in two states: 1) the target would dock a dockable that is presently above it if the mouse would be released; 2) something else.

Five elementary operations that may be performed by a "docking target widget" have been identified. The recipe to define a new "docking target widget" class requires that this class defines 2 to 5 static functions that perform some or all of these elementary operations according to what is expected from the class:

1. Is the mouse, which is presently dragging a dockable-containing window, above the target's docking area?
2. Is the given dockable acceptable by the given target widget?
3. Redraw the target widget according to whether it's ready to dock a dockable.
4. Insert the dockable widget re-organizing the target widget accordingly.
5. Perform operations necessary after the dockable was undocked from the target, if any.

These operations are believed to contain all ways by which possible docking targets may differ. FLTK performs all the mechanics of receiving events, transmitting them from containers to widgets, working differently under Wayland than under other platforms, and calling each elementary operation when appropriate.

Following a very clever suggestion by @CyprinusCarpio, FLTK uses internally 5 newly defined docking-related events: FL_DOCK_ENTER, FL_DOCK_DRAG, FL_DOCK_RELEASE, FL_DOCK_LEAVE and FL_UNDOCK. The docking operation creates a situation that is new in FLTK where a single event, a mouse button drag or release, is of direct interest to two widgets from two windows: the active dockable and the target widget below it. Therefore, the new events, say FL_DOCK_RELEASE, are sent internally by FLTK to docking target widgets, and also to the dockable which can receive them via its handle(int) method and act accordingly. Furthermore, only under the Wayland platform, the docking/undocking mechanism is implemented as a modified drag-and-drop and generates FL_DND_ENTER, FL_DND_DRAG, … events. These are transformed internally by FLTK into FL_DOCK_ENTER, FL_DOCK_DRAG, … events to become platform-independent FLTK events sent to Fl_Widget's as usual.

There are 2 quite distinct implementations behind class Fl_Dockable_Group. This explains the need of class Fl_Dockable_Group_Driver, internal to FLTK. One is for all platforms where the position of a window in a display can be programmatically set and read (macOS, X11, Windows). Any future FLTK platform with this property would not need special development for class Fl_Dockable_Group. The second is Wayland-specific.

The new class requires a few changes to the FLTK core:

• new events FL_DOCK_* + FL_UNDOCK
• Wayland only: add support of the "XDG toplevel drag" protocol; define a new DND kind that carries a window rather than text or filenames; add a few checks needed to distinguish text DND from window DND.

Program test/dock_undock.cxx contains the complete implementations of 4 kinds of docking target widgets:

1. The simplest docking target where an Fl_Dockable_Group::Docking_Target_Box is put in an Fl_Window. No user code is necessary beyond construction of a Docking_Target_Box object.
2. A Fl_Dockable_Group::Docking_Target_Box inside an Fl_Tile object.
3. A docking target derived from Fl_Flex featuring a docking area which appears ready to dock a dragged dockable under appropriate conditions. All 5 elementary operations are implemented for this widget.
4. A docking target derived from Fl_Tabs that allows to undock a child dockable by a click/drag operation on the child's tab area, and to dock a dragged dockable when the mouse is in the Fl_Tabs' tabs area. This shows an implementation of an advanced form of docking target where events outside the drag widget are recruited to undock the dockable.

I have a question. If you want to have a Fl_Dockable_Group that allows docking multiple "drag widgets" and packing them? How would you go about it? Can you derive from both Fl_Dockable_Group and Fl_Flex for example? Or would you derive from Fl_Dockable_Group and have to re-code most of Fl_Flex again?

@ManoloFLTK Got it now. I looked at the code. The handle_docking_target function REALLY needs proper documentation as it allows you to do a lot of things.