* Reorders children within the child Widget array. Assists with z-order

     * operations on child Widgets.

     *

     * Child Widgets of parent are reordered in Array per the provided List of 

     * Integer

     *  

     * @param permutation List<Integer> consisting of new order. Each array slot

     * contains Integer value pointing to the old Objects index

     */

    public final void orderChildren(List<Integer> permutation) {

        assert permutation != null;

        if (parentWidget == null)

            return;

        List<Widget> widgets = parentWidget.children;

        assert permutation.size() == widgets.size();

        List<Widget> newOrder = new ArrayList<Widget>();

        for ( int j = 0 ; j < widgets.size(); j++) {

          Integer oldIndex = permutation.get(j);

          newOrder.add(widgets.get(oldIndex.intValue()));

        }

        widgets.clear();

        widgets.addAll(newOrder);

        revalidate ();

        parentWidget.revalidate ();

    }

    /**