<change>

            <api name="general"/>

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

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

            <date day="15" month="2" 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>

import javax.accessibility.Accessible;

    /**

     * 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.

     * @since 2.11

     */

    public final void orderChildren(List<? extends Widget> permutation) {

        if (permutation == null  ||  permutation.size() != children.size ())

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

        for (Widget widget : permutation)

            if (! children.contains (widget))

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

        for (Widget widget : children)

            if (! permutation.contains (widget))

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

        children.clear ();

        children.addAll (permutation);

        revalidate ();

        for (Widget child : children)

            child.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

 * @since 2.11

 */

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

     * @since 2.11

     */

    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<Widget> permutation = new ArrayList<Widget>(children);

        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

     * @since 2.11

     */

    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<Widget> permutation = new ArrayList<Widget>(children);

        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);

        LabelWidget label4 = new LabelWidget (scene, "4");

        scene.orderChildren (Arrays.asList (label2, label3, label0, label1));

        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));

        try {

            scene.orderChildren (Arrays.asList (label3, label0, label1));

            assertTrue (false);

        } catch (IllegalArgumentException e) {

//            e.printStackTrace ();

        }

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

        try {

            scene.orderChildren (Arrays.asList (label3, label0, label1, label4));

            assertTrue (false);

        } catch (IllegalArgumentException e) {

//            e.printStackTrace ();

        }

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

        try {

            scene.orderChildren (Arrays.asList (label0, label1, label2, label3, label4));

            assertTrue (false);

        } catch (IllegalArgumentException e) {

//            e.printStackTrace ();

        }

        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 ();

    }

}