<change id="ServerSideQueries">

        <api name="refactoring"/>

        <summary>Added support for Scope Providers and ExpandableTreeElements.</summary>

        <version major="1" minor="30"/>

        <date day="31" month="8" year="2012"/>

        <author login="ralphbenjamin"/>

        <compatibility addition="yes"/>

        <description>

            <p>

                Added an ExpandableTreeElement and a declarative way to add new scopes.

            </p>

        </description>

        <class package="org.netbeans.modules.refactoring.spi.ui" name="ExpandableTreeElement"/>

        <class package="org.netbeans.modules.refactoring.spi.ui" name="ScopeProvider"/>

        <class package="org.netbeans.modules.refactoring.spi.ui" name="ScopeDescription"/>

        <class package="org.netbeans.modules.refactoring.spi.ui" name="ScopeReference"/>

        <class package="org.netbeans.modules.refactoring.spi.ui" name="ScopeReferences"/>

        <class package="org.netbeans.modules.refactoring.spi.ui" name="ScopePanel"/>

        <issue number="217347"/>

    </change>

LBL_Scope=Sco&pe:

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

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

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.refactoring.spi.ui;

import org.openide.util.Cancellable;

/**

 * ExpandableTreeElements are shown in the Find Usages results.

 * ExpandableTreeElement allows a TreeElement to have children. It will be

 * iterated when the TreeElement is expanded. The iterator is allowed to block,

 * it will be called from outside of AWT.

 * 

 * @author Jan Lahoda

 * @author Ralph Benjamin Ruijs <ralphbenjamin@netbeans.org>

 * @see TreeElement

 * @since 1.30

 */

public interface ExpandableTreeElement extends TreeElement, Iterable<TreeElement>, Cancellable {

    /**

     * Gives an estimate of the amount of children this element has.

     * The estimatedChildCount will be used to give the user a rough count

     * of found occurrences.

     * @return the estimated child count

     */

    public int estimateChildCount();

}

<?xml version="1.0" encoding="UTF-8" ?>

<Form version="1.5" maxVersion="1.8" type="org.netbeans.modules.form.forminfo.JPanelFormInfo">

  <AuxValues>

    <AuxValue name="FormSettings_autoResourcing" type="java.lang.Integer" value="1"/>

    <AuxValue name="FormSettings_autoSetComponentName" type="java.lang.Boolean" value="false"/>

    <AuxValue name="FormSettings_generateFQN" type="java.lang.Boolean" value="true"/>

    <AuxValue name="FormSettings_generateMnemonicsCode" type="java.lang.Boolean" value="true"/>

    <AuxValue name="FormSettings_i18nAutoMode" type="java.lang.Boolean" value="true"/>

    <AuxValue name="FormSettings_layoutCodeTarget" type="java.lang.Integer" value="1"/>

    <AuxValue name="FormSettings_listenerGenerationStyle" type="java.lang.Integer" value="0"/>

    <AuxValue name="FormSettings_variablesLocal" type="java.lang.Boolean" value="false"/>

    <AuxValue name="FormSettings_variablesModifier" type="java.lang.Integer" value="2"/>

  </AuxValues>

  <Layout>

    <DimensionLayout dim="0">

      <Group type="103" groupAlignment="0" attributes="0">

          <Group type="102" alignment="0" attributes="0">

              <Component id="scopeCombobox" pref="343" max="32767" attributes="0"/>

              <EmptySpace max="-2" attributes="0"/>

              <Component id="btnCustomScope" min="-2" max="-2" attributes="0"/>

          </Group>

      </Group>

    </DimensionLayout>

    <DimensionLayout dim="1">

      <Group type="103" groupAlignment="0" attributes="0">

          <Group type="103" alignment="0" groupAlignment="3" attributes="0">

              <Component id="btnCustomScope" alignment="3" min="-2" max="-2" attributes="0"/>

              <Component id="scopeCombobox" alignment="3" min="-2" max="-2" attributes="1"/>

          </Group>

      </Group>

    </DimensionLayout>

  </Layout>

  <SubComponents>

    <Component class="javax.swing.JButton" name="btnCustomScope">

      <Properties>

        <Property name="action" type="javax.swing.Action" editor="org.netbeans.modules.form.RADConnectionPropertyEditor">

          <Connection code="new ScopeAction(scopeCombobox)" type="code"/>

        </Property>

        <Property name="text" type="java.lang.String" value="..." noResource="true"/>

      </Properties>

    </Component>

    <Component class="javax.swing.JComboBox" name="scopeCombobox">

      <Properties>

        <Property name="renderer" type="javax.swing.ListCellRenderer" editor="org.netbeans.modules.form.RADConnectionPropertyEditor">

          <Connection code="new ScopeDescriptionRenderer()" type="code"/>

        </Property>

      </Properties>

      <Events>

        <EventHandler event="actionPerformed" listener="java.awt.event.ActionListener" parameters="java.awt.event.ActionEvent" handler="scopeComboboxActionPerformed"/>

      </Events>

      <AuxValues>

        <AuxValue name="JavaCodeGenerator_InitCodePost" type="java.lang.String" value="((javax.swing.JTextField) scopeCombobox.getEditor().getEditorComponent()).setColumns(SCOPE_COMBOBOX_COLUMNS);"/>

      </AuxValues>

    </Component>

  </SubComponents>

</Form>

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

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

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.refactoring.spi.ui;

import java.awt.Component;

import java.awt.event.ActionEvent;

import java.util.ArrayList;

import java.util.Collection;

import java.util.Collections;

import java.util.Comparator;

import java.util.List;

import java.util.concurrent.atomic.AtomicBoolean;

import java.util.prefs.Preferences;

import javax.swing.AbstractAction;

import javax.swing.ComboBoxModel;

import javax.swing.DefaultComboBoxModel;

import javax.swing.JComboBox;

import javax.swing.JLabel;

import javax.swing.JList;

import javax.swing.ListCellRenderer;

import javax.swing.SwingUtilities;

import javax.swing.plaf.UIResource;

import org.netbeans.api.annotations.common.CheckForNull;

import org.netbeans.api.annotations.common.NonNull;

import org.netbeans.modules.refactoring.api.Scope;

import org.netbeans.modules.refactoring.spi.impl.DelegatingCustomScopeProvider;

import org.netbeans.modules.refactoring.spi.impl.DelegatingScopeInformation;

import org.openide.util.Lookup;

import org.openide.util.lookup.Lookups;

/**

 * ScopePanel provides a component to use for scope selection. A customize

 * button (a JButton with ellipses) will be displayed when any of the registered

 * scopes is customizable.

 *

 * @author Ralph Benjamin Ruijs <ralphbenjamin@netbeans.org>

 * @since 1.30

 */

public final class ScopePanel extends javax.swing.JPanel {

    private static final String ELLIPSIS = "\u2026"; //NOI18N

    private static final int SCOPE_COMBOBOX_COLUMNS = 14;

    private final String id;

    private final Preferences preferences;

    private final String preferencesKey;

    private ArrayList<DelegatingScopeInformation> scopes;

    /**

     * Creates new form ScopePanel.

     *

     * @deprecated do not use this constructor. Only available for the Matisse

     * GUI-builder.

     */

    @Deprecated

    public ScopePanel() {

        this(null, null, null);

    }

    /**

     * Creates a new ScopePanel. The supplied id will be used to only get the

     * Scopes registered for a specific set of Scopes. The preferences and

     * preferencesKey will be used to store the user's selection.

     *

     * @param id the id for which the scopes are registered

     * @param preferences a preferences object to store user's selection

     * @param preferencesKey a key to use to store user's selection

     */

    public ScopePanel(String id, Preferences preferences, String preferencesKey) {

        this.id = id;

        this.preferences = preferences;

        this.preferencesKey = preferencesKey;

        this.scopes = new ArrayList<DelegatingScopeInformation>();

        initComponents();

    }

    /**

     * Initializes the Combobox and customize button of this ScopePanel. The

     * context will be passed to the different ScopeProviders initialize method.

     * This method will return false if there are no available scopes and this

     * panel should not be available to the user.

     *

     * @param context the Lookup to pass to the ScopeProviders

     * @return true if there is at least one Scope available, false otherwise

     */

    public boolean initialize(Lookup context, AtomicBoolean cancel) {

        scopes.clear();

        Collection<? extends ScopeProvider> scopeProviders = Lookups.forPath("Scopes" + "/" + id).lookupAll(ScopeProvider.class);

        final AtomicBoolean customizable = new AtomicBoolean();

        for (ScopeProvider provider : scopeProviders) {

            if (provider.initialize(context, new AtomicBoolean())) {

                scopes.add((DelegatingScopeInformation)provider);

                if (provider instanceof ScopeProvider.CustomScopeProvider) {

                    customizable.set(true);

                }

            }

        }

        Collections.sort(scopes, new Comparator<DelegatingScopeInformation>() {

            @Override

            public int compare(DelegatingScopeInformation o1, DelegatingScopeInformation o2) {

                return (o1.getPosition() < o2.getPosition() ? -1 : (o1.getPosition() == o2.getPosition() ? 0 : 1));

            }

        });

        if (!scopes.isEmpty()) {

            SwingUtilities.invokeLater(new Runnable() {

                @Override

                public void run() {

                    scopeCombobox.setModel(new DefaultComboBoxModel(scopes.toArray(new ScopeProvider[scopes.size()])));

                    for (DelegatingScopeInformation scopeProvider : scopes) {

                        if(scopeProvider instanceof ScopeProvider.CustomScopeProvider) {

                            ScopePanel.this.btnCustomScope.setVisible(false);

                            break;

                        }

                    }

                    String preselectId = preferences.get(preferencesKey, null);

                    if (preselectId == null) { // Needed for the old preferences of Java's Where Used Panel.

                        int defaultItem = (Integer) preferences.getInt(preferencesKey, -1); // NOI18N

                        if (defaultItem != (-1)) {

                            switch (defaultItem) {

                                case 0:

                                    preselectId = "all-projects";

                                    break;

                                case 1:

                                    preselectId = "current-project";

                                    break;

                                case 2:

                                    preselectId = "current-package";

                                    break;

                                case 3:

                                    preselectId = "current-file";

                                    break;

                                case 4:

                                    preselectId = "custom-scope";

                                    break;

                            }

                        }

                    }

                    if (preselectId != null) {

                        selectScopeById(preselectId);

                    } else {

                        selectPreferredScope();

                    }

                }

            });

        }

        return !scopes.isEmpty();

    }

    /**

     * The currently selected scope in the Combobox. This can be a predefined

     * scope, or a customized one.

     *

     * @return the selected Scope

     */

    @CheckForNull

    public Scope getSelectedScope() {

        return ((ScopeProvider) scopeCombobox.getSelectedItem()).getScope();

    }

    /**

     * Change the selected scope to one with the specified id. If the id does

     * not exist, nothing is changed. When the id is from a CustomScopeProvider

     * and it returns an empty scope, the preferred scope is selected.

     *

     * @see ScopeProvider.CustomScopeProvider

     *

     * @param id the id of the scope to select

     */

    public void selectScopeById(@NonNull String id) {

        ComboBoxModel m = scopeCombobox.getModel();

        for (int i = 0; i < m.getSize(); i++) {

            DelegatingScopeInformation sd = (DelegatingScopeInformation) m.getElementAt(i);

            if (sd.getId().equals(id)) {

                if (sd instanceof ScopeProvider.CustomScopeProvider) {

                    Scope s = sd.getScope();

                    if (s != null

                            && s.getFiles().isEmpty()

                            && s.getFolders().isEmpty()

                            && s.getSourceRoots().isEmpty()) {

                        selectPreferredScope();

                        return;

                    }

                }

                scopeCombobox.setSelectedItem(sd);

                return;

            }

        }

    }

    /**

     * This method is called from within the constructor to initialize the form.

     * WARNING: Do NOT modify this code. The content of this method is always

     * regenerated by the Form Editor.

     */

    @SuppressWarnings("unchecked")

    // <editor-fold defaultstate="collapsed" desc="Generated Code">//GEN-BEGIN:initComponents

    private void initComponents() {

        btnCustomScope = new javax.swing.JButton();

        scopeCombobox = new javax.swing.JComboBox();

        btnCustomScope.setAction(new ScopeAction(scopeCombobox));

        org.openide.awt.Mnemonics.setLocalizedText(btnCustomScope, "..."); // NOI18N

        scopeCombobox.setRenderer(new ScopeDescriptionRenderer());

        ((javax.swing.JTextField) scopeCombobox.getEditor().getEditorComponent()).setColumns(SCOPE_COMBOBOX_COLUMNS);

        scopeCombobox.addActionListener(new java.awt.event.ActionListener() {

            public void actionPerformed(java.awt.event.ActionEvent evt) {

                scopeComboboxActionPerformed(evt);

            }

        });

        javax.swing.GroupLayout layout = new javax.swing.GroupLayout(this);

        this.setLayout(layout);

        layout.setHorizontalGroup(

            layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)

            .addGroup(layout.createSequentialGroup()

                .addComponent(scopeCombobox, 0, 343, Short.MAX_VALUE)

                .addPreferredGap(javax.swing.LayoutStyle.ComponentPlacement.RELATED)

                .addComponent(btnCustomScope))

        );

        layout.setVerticalGroup(

            layout.createParallelGroup(javax.swing.GroupLayout.Alignment.LEADING)

            .addGroup(layout.createParallelGroup(javax.swing.GroupLayout.Alignment.BASELINE)

                .addComponent(btnCustomScope)

                .addComponent(scopeCombobox, javax.swing.GroupLayout.PREFERRED_SIZE, javax.swing.GroupLayout.DEFAULT_SIZE, javax.swing.GroupLayout.PREFERRED_SIZE))

        );

    }// </editor-fold>//GEN-END:initComponents

    private void scopeComboboxActionPerformed(java.awt.event.ActionEvent evt) {//GEN-FIRST:event_scopeComboboxActionPerformed

        preferences.putInt(preferencesKey, scopeCombobox.getSelectedIndex());

    }//GEN-LAST:event_scopeComboboxActionPerformed

    // Variables declaration - do not modify//GEN-BEGIN:variables

    private javax.swing.JButton btnCustomScope;

    private javax.swing.JComboBox scopeCombobox;

    // End of variables declaration//GEN-END:variables

    private void selectPreferredScope() {

        ComboBoxModel m = scopeCombobox.getModel();

        for (int i = 0; i < m.getSize(); i++) {

            DelegatingScopeInformation sd = (DelegatingScopeInformation) m.getElementAt(i);

            if (sd.getPosition() >= 0) {

                scopeCombobox.setSelectedItem(sd);

                return;

            }

        }

    }

    private class ScopeAction extends AbstractAction {

        private final JComboBox scopeCombobox;

        private ScopeAction(JComboBox scopeCombobox) {

            this.scopeCombobox = scopeCombobox;

            this.putValue(NAME, ELLIPSIS);

        }

        @Override

        public void actionPerformed(ActionEvent e) {

            ComboBoxModel m = this.scopeCombobox.getModel();

            ScopeProvider selectedScope = (ScopeProvider) scopeCombobox.getSelectedItem();

            Scope scope = selectedScope.getScope();

            if (selectedScope instanceof DelegatingCustomScopeProvider) {

                showCustomizer((DelegatingCustomScopeProvider) selectedScope, scope);

            } else {

                for (int i = 0; i < m.getSize(); i++) {

                    ScopeProvider sd = (ScopeProvider) m.getElementAt(i);

                    if (sd instanceof DelegatingCustomScopeProvider) {

                        showCustomizer((DelegatingCustomScopeProvider) sd, scope);

                        break;

                    }

                }

            }

        }

        private void showCustomizer(DelegatingCustomScopeProvider csd, Scope scope) {

            csd.setScope(scope);

            if (csd.showCustomizer()) {

                selectScopeById(csd.getId());

            }

        }

    }

    private static class ScopeDescriptionRenderer extends JLabel implements ListCellRenderer, UIResource {

        public ScopeDescriptionRenderer() {

            setOpaque(true);

        }

        @Override

        public Component getListCellRendererComponent(

                JList list,

                Object value,

                int index,

                boolean isSelected,

                boolean cellHasFocus) {

            // #89393: GTK needs name to render cell renderer "natively"

            setName("ComboBox.listRenderer"); // NOI18N

            DelegatingScopeInformation scopeDescription = null;

            if (value instanceof DelegatingScopeInformation) {

                scopeDescription = (DelegatingScopeInformation) value;

            }

            if (scopeDescription != null) {

                String detail = scopeDescription.getDetail();

                String displayName = scopeDescription.getDisplayName();

                setText(detail == null ? displayName : displayName + " (" + detail + ")");

                setIcon(scopeDescription.getIcon());

            }

            if (isSelected) {

                setBackground(list.getSelectionBackground());

                setForeground(list.getSelectionForeground());

            } else {

                setBackground(list.getBackground());

                setForeground(list.getForeground());

            }

            return this;

        }

        // #89393: GTK needs name to render cell renderer "natively"

        @Override

        public String getName() {

            String name = super.getName();

            return name == null ? "ComboBox.renderer" : name;  // NOI18N

        }

    }

}

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

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

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.refactoring.spi.ui;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

import java.util.concurrent.atomic.AtomicBoolean;

import javax.swing.Icon;

import org.netbeans.api.annotations.common.CheckForNull;

import org.netbeans.api.annotations.common.NonNull;

import org.netbeans.api.annotations.common.NullAllowed;

import org.netbeans.modules.refactoring.api.Scope;

import org.openide.util.Lookup;

/**

 * ScopeProvider is used to add a scope to the {@link ScopePanel}.

 *

 * @see ScopePanel

 * @see ScopeDescription

 * @see ScopeReference

 *

 * @author Jan Lahoda

 * @author Ralph Benjamin Ruijs <ralphbenjamin@netbeans.org>

 *

 * @since 1.30

 */

public abstract class ScopeProvider {

    /**

     * Initialize this scope provider with the supplied context.

     *

     * @param context a Lookup defining the context

     * @param cancel set to true if initialization should be canceled

     * @return true if this scope is usable for the supplied context, false

     * otherwise

     */

    public abstract boolean initialize(@NonNull Lookup context, @NonNull AtomicBoolean cancel);

    /**

     * Get this provider's scope. The scope can be null if this provider is not

     * yet initialized, or this provider is not usable for the supplied context.

     *

     * @see ScopeProvider#initialize(org.openide.util.Lookup,

     * java.util.concurrent.atomic.AtomicBoolean)

     * @return the Scope

     */

    @CheckForNull

    public abstract Scope getScope();

    /**

     * Override this method if the icon should be different depending on the

     * context.

     *

     * @see ScopeProvider#initialize(org.openide.util.Lookup,

     * java.util.concurrent.atomic.AtomicBoolean)

     * @see ScopeDescription

     * @return an icon for the Scope, or null if the default should be used.

     */

    @CheckForNull

    public Icon getIcon() {

        return null;

    }

    /**

     * Override this method if an explaining string should be displayed behind

     * the scope's name. This is used for scopes like "- Current File

     * (Filename.java)".

     *

     * @return an explaining string, or null of nothing should be displayed.

     */

    @CheckForNull

    public String getDetail() {

        return null;

    }

    /**

     * The CustomScopeProvider extends the normal scope provider to support

     * scopes which can be customized by the user.

     *

     * @see ScopePanel

     * @see ScopeDescription

     * @see ScopeReference

     *

     * @author Jan Lahoda

     * @author Ralph Benjamin Ruijs <ralphbenjamin@netbeans.org>

     *

     * @since 1.30

     */

    public static abstract class CustomScopeProvider extends ScopeProvider {

        /**

         * Set the scope to be customized. This method will be called right

         * before the provider is asked to show the customizer, with the

         * currently selected scope.

         *

         * @param currentScope the Scope currently selected

         */

        public abstract void setScope(@NullAllowed Scope currentScope);

        /**

         * Show a Dialog to customize the scope.

         *

         * @return true if the user succesfully specified a scope, false

         * otherwise (ie. clicked cancel)

         */

        public abstract boolean showCustomizer();

    }

    /**

     * Declarative registration of a ScopeProvider implementation.

     * By marking the implementation class with this annotation,

     * you automatically register that implementation.

     * The class must be public and have a public constructor which takes

     * no arguments.

     * 

     * @author Jan Lahoda

     * @author Ralph Benjamin Ruijs <ralphbenjamin@netbeans.org>

     * @since 1.30

     */

    @Target({ElementType.TYPE})

    @Retention(RetentionPolicy.SOURCE)

    public static @interface Registration {

        /**

         * The unique ID of the scope description.

         *

         * @return unique id

         */

        String id();

        /**

         * Position in the location. Negative numbers can be used for scopes

         * that should be higher in the list, but not selected by default.

         */

        int position() default Integer.MAX_VALUE;

        /**

         * Display name. Usually prefixed with '#' to reference value from a

         * <code>Bundle.properties</code> file in the same package.

         *

         * @return display name for the scope

         */

        String displayName();

        /**

         * Path to image representing the scope's icon.

         *

         * @return "org/myproject/mypkg/Icon.png"

         */

        String iconBase() default "";

    }

}

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

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

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.refactoring.spi.ui;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

/**

 * A reference to a Scope Description to be used by a {@link ScopePanel}

 *

 * @author Ralph Benjamin Ruijs <ralphbenjamin@netbeans.org>

 * @since 1.30

 */

@Target({ElementType.TYPE})

@Retention(RetentionPolicy.SOURCE)

public @interface ScopeReference {

    /**

     * Into which location one wants to place the reference? Translates to

     * {@link FileUtil#getConfigFile(java.lang.String)}.

     */

    String path();

    /**

     * Identification of the scope this reference shall point to. Usually this

     * is specified as {@link ScopeDescription} peer annotation, but in case one

     * was to create references to scopes defined by someone else, one can

     * specify the id() here.

     */

    String id() default "";

}

/*

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

 *

 * Copyright 2012 Oracle and/or its affiliates. All rights reserved.

 *

 * Oracle and Java are registered trademarks of Oracle and/or its affiliates.

 * Other names may be trademarks of their respective owners.

 *

 * 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.  Oracle designates this

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

 * by Oracle 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]"

 *

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

 *

 * Contributor(s):

 *

 * Portions Copyrighted 2012 Sun Microsystems, Inc.

 */

package org.netbeans.modules.refactoring.spi.ui;

import java.lang.annotation.ElementType;

import java.lang.annotation.Retention;

import java.lang.annotation.RetentionPolicy;

import java.lang.annotation.Target;

/**

 * Allows registration of multiple {@link ScopeReference}s for a single type.

 *

 * @author Ralph Benjamin Ruijs <ralphbenjamin@netbeans.org>

 */

@Target({ElementType.TYPE})

@Retention(RetentionPolicy.SOURCE)

public @interface ScopeReferences {

    ScopeReference[] value();

}