Conceptually, the Overlays should be seen as additional layers in the desktop rendering, as shown in the following diagram. An explanation of the expected behavior for each layer follows.
Currently, the behavior of the Sugar Shell exhibits an implicit 3 layer structure. The Activity/View displays things on layer "5". Sometimes, like for Journal entries, a popup menu will show up at layer 3. The Frame still show up on top of that pop-up at layer 2. To allow showing tutoring elements we need at least two other layers, one for the Frame (1) and one for Activities/Views (4). In the future, we might even like to have another Layer to display tutoring elements on top of popup menus but for now those are not strictly needed. The Frame Overlay should hide and show with the Frame. Each Activity and View should have its own Overlay that would also hide and show with it.
The order of the layers should stay the same, even if the Frame is shown/hidden and even if Views/Activities are switched.
The main problem we had trying to implement that layering is caused by the relative order of windows used by GTK. It is possible to add a constraint on a window so that it always shows on top of another but we haven't found a way to force a window to be "sandwiched" between two others. From the little experiments we did, it seems that sometimes, windows are fighting to be on top. Also, when switching views, the corresponding overlays would simply disappear. We guess the ordering of the windows was not preserved. I guess there might be a way to achieve it using Composition but at this point, I don't know if it is supported by Sugar and how it should be implemented. I will have a second try at this in the next weeks. In the meantime, if anyone has an idea how to implement it is welcome to add a code sample/patch on this page.
Also, the extra windows induced by overlays are seen as "Activities" in the activity tray (grey dots). I have not yet found a way to prevent those from being displayed. Any suggestion is welcomed.