Force containers to be list-like

["BJörn Lindqvist" <bjourne gmail com>]

Hello good people,

I think there should be a contract that all subclasses of GtkContainer
must implement. Conceptually, a container is a collection of
widgets. Usually that collection is implemented as a list but it does
not have to be [1]. This means that:

1. The order child widgets are stored in may not be the same as the
   order they were added in. This code might not work:

    w1 = gtk.Button()
    w2 = gtk.Button()
    container = RandomContainer()
    container.add(w1)
    container.add(w2)
    assert container.get_children() == [w1, w2]

2. Since the order is not guaranteed it may change for any
   reason. This code might not work:

   w1 = gtk.Button()
   w2 = gtk.Button()
   container = RandomContainer()
   c1 = container.get_children()
   c2 = container.get_children()
   assert c1 == c2

Because those two invariants cannot be guaranteed, it becomes harder
than it has to be to make z-order work properly, see #550345.

The solution I propose is to require all container implementations to
behave list-like so that the above code always works by specifying in
the docs the contract that they need to full fill. I don't think that
should break any code whatsoever even if it in theory is an ABI
break. The big gain is that widgets gets an implied z-order which
makes overlapping widgets work.

In the future (3.0 maybe?) it would be cool if there was a Sequence
interface that container widgets could implement. That way it would be
more explicit how containers should be implemented. And other
list-like widgets could also implement that interface (GtkListStore,
GtkCellView and GtkMenuShell for example). But for now the contract
would suffice.

[1] - It could be a set for example.


-- 
mvh Björn