<change>

            <api name="general"/>

            <summary>Support of Widget children ordering</summary>

            <version major="2" minor="11"/>

            <date day="7" month="1" year="2008"/>

            <author login="dkaspar"/>

            <compatibility addition="yes"/>

            <description>

                New methods of Widget children ordering introduced: Widget.orderChildren, WidgetSupport.bringBackward and WidgetSupport.bringForward.

            </description>

            <class package="org.netbeans.api.visual.widget" name="Widget" link="yes"/>

            <issue number="121525"/>

        </change>

     * Reorders children with specified permutation.

     * @param permutation List<Integer> consisting of new order. Each array slot contains Integer value pointing to a Widget at particular index in previous order.

     */

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

        assert permutation != null;

        int size = children.size ();

        assert permutation.size() == size;

        Widget[] previous = children.toArray (new Widget[size]);

        Widget[] newOrder = new Widget[size];

        children.clear ();

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

            int index = permutation.get(j);

            Widget child = previous[index];

            if (child == null)

                throw new IllegalArgumentException("Invalid permutation: " + permutation);

            newOrder[j] = child;

            previous[index] = null;

        }

        for (int j = 0; j < size; j ++)

            if (previous[j] != null)

                throw new IllegalArgumentException("Invalid permutation: " + permutation);

        children.clear();

        children.addAll(Arrays.asList (newOrder));

        revalidate ();

        for (int j = 0; j < size; j ++)

            newOrder[j].revalidate ();

    }

    /**

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun

 * Microsystems, Inc. All Rights Reserved.

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 */

package org.netbeans.api.visual.widget;

import java.util.ArrayList;

import java.util.List;

/**

 * Support methods for Widget manipulation.

 * 

 * @author cpalmer

 */

public final class WidgetSupport {

    private WidgetSupport() {

    }

    /**

     * Brings the widget 1 slot backward in the parent Widget child array. 

     * Means: the widget is moving towards the first child in the list of children of the parent widget.

     * @param childWidget Widget that is sent backwards in the list of children

     */

    public static void bringBackward (Widget childWidget) {

        if (childWidget == null)

            return;

        Widget parentWidget = childWidget.getParentWidget ();

        if (parentWidget == null)

            return;

        List<Widget> children = parentWidget.getChildren();

        int i = children.indexOf (childWidget);

        if (i <= 0)

            return;

        List<Integer> permutation = new ArrayList<Integer>();

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

            permutation.add (j);

        permutation.add(i-1,permutation.remove(i));

        parentWidget.orderChildren(permutation);

    }

    /**

     * Brings the widget 1 slot forward in the parent Widget child array. 

     * Means: the widget is moving towards the last child in the list of children of the parent widget.

     * @param childWidget Widget that is brought forward in the list of children

     */

    public static void bringForward (Widget childWidget) {

        if (childWidget == null)

            return;

        Widget parentWidget = childWidget.getParentWidget ();

        if (parentWidget == null)

            return;

        List<Widget> children = parentWidget.getChildren();

        int i = children.indexOf (childWidget);

        if (i < 0 || i == (children.size()-1) )

            return;

        List<Integer> permutation = new ArrayList<Integer>();

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

            permutation.add(j);

        permutation.add(i+1,permutation.remove(i));

        parentWidget.orderChildren(permutation);

    }

}

/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

 *

 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.

 *

 * The contents of this file are subject to the terms of either the GNU

 * General Public License Version 2 only ("GPL") or the Common

 * Development and Distribution License("CDDL") (collectively, the

 * "License"). You may not use this file except in compliance with the

 * License. You can obtain a copy of the License at

 * http://www.netbeans.org/cddl-gplv2.html

 * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the

 * specific language governing permissions and limitations under the

 * License.  When distributing the software, include this License Header

 * Notice in each file and include the License file at

 * nbbuild/licenses/CDDL-GPL-2-CP.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the GPL Version 2 section of the License file that

 * accompanied this code. If applicable, add the following below the

 * License Header, with the fields enclosed by brackets [] replaced by

 * your own identifying information:

 * "Portions Copyrighted [year] [name of copyright owner]"

 *

 * Contributor(s):

 *

 * The Original Software is NetBeans. The Initial Developer of the Original

 * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun

 * Microsystems, Inc. All Rights Reserved.

 *

 * If you wish your version of this file to be governed by only the CDDL

 * or only the GPL Version 2, indicate your decision by adding

 * "[Contributor] elects to include this software in this distribution

 * under the [CDDL or GPL Version 2] license." If you do not indicate a

 * single choice of license, a recipient has the option to distribute

 * your version of this file under either the CDDL, the GPL Version 2 or

 * to extend the choice of license to its licensees as provided above.

 * However, if you add GPL Version 2 code and therefore, elected the GPL

 * Version 2 license, then the option applies only if the new code is

 * made subject to such option by the copyright holder.

 */

package apichanges;

import org.netbeans.api.visual.widget.LabelWidget;

import org.netbeans.api.visual.widget.Scene;

import org.netbeans.api.visual.widget.Widget;

import org.netbeans.api.visual.widget.WidgetSupport;

import org.netbeans.junit.NbTestCase;

import java.util.Arrays;

/**

 * Test for #121525 - Widget.orderChildren

 * @author David Kaspar

 */

public class WidgetOrderTest extends NbTestCase {

    public WidgetOrderTest (String testName) {

        super (testName);

    }

    public void testOrder () {

        Scene scene = new Scene ();

        LabelWidget label0 = new LabelWidget (scene, "0");

        scene.addChild (label0);

        LabelWidget label1 = new LabelWidget (scene, "1");

        scene.addChild (label1);

        LabelWidget label2 = new LabelWidget (scene, "2");

        scene.addChild (label2);

        LabelWidget label3 = new LabelWidget (scene, "3");

        scene.addChild (label3);

        scene.orderChildren (Arrays.asList (2, 3, 0, 1));

        assertEquals ("2,3,0,1,", dumpOrder (scene));

        WidgetSupport.bringForward (label0);

        assertEquals ("2,3,1,0,", dumpOrder (scene));

        WidgetSupport.bringBackward (label3);

        assertEquals ("3,2,1,0,", dumpOrder (scene));

    }

    private static String dumpOrder (Scene scene) {

        StringBuffer buffer = new StringBuffer ();

        for (Widget child : scene.getChildren ()) {

            LabelWidget label = (LabelWidget) child;

            buffer.append (label.getLabel ()).append (',');

        }

        return buffer.toString ();

    }

}