org.netbeans.api.project.ui

Class OpenProjects

java.lang.Object

org.netbeans.api.project.ui.OpenProjects

public final class OpenProjects
extends Object

List of projects open in the GUI.

Warning: this API is intended only for a limited set of use cases where obtaining a list of all open projects is really the direct goal. For example, you may wish to display a chooser letting the user select a file from among the top-level source folders of any open project. For many cases, however, this API is not the correct approach, so use it as a last resort. Consider GlobalPathRegistry, ProjectOpenedHook, and ProjectSensitiveActions (or MainProjectSensitiveActions) first. Only certain operations should actually be aware of which projects are "open"; by default, all project functionality should be available whether it is open or not.

Field Summary

Fields

Modifier and Type	Field and Description
static String	PROPERTY_MAIN_PROJECT Property representing main project.
static String	PROPERTY_OPEN_PROJECTS Property representing open projects.

Method Summary

Methods

Modifier and Type	Method and Description
void	addProjectGroupChangeListener(ProjectGroupChangeListener listener) add listener to changes in active project group
void	addPropertyChangeListener(PropertyChangeListener listener) Adds a listener to changes in the set of open projects.
void	close(Project[] projects) Closes given projects.
ProjectGroup	getActiveProjectGroup() return the currently action project group
static OpenProjects	getDefault() Get the default singleton instance of this class.
Project	getMainProject() Retrieves the current main project set in the IDE.
Project[]	getOpenProjects() Gets a list of currently open projects.
boolean	isProjectOpen(Project p) Finds out if the project is opened.
void	open(Project[] projects, boolean openSubprojects) Opens given projects.
void	open(Project[] projects, boolean openSubprojects, boolean showProgress) Opens given projects.
Future<Project[]>	openProjects() Method to track progress of projects opening and closing.
void	removeProjectGroupChangeListener(ProjectGroupChangeListener listener) remove listener to changes in active project group
void	removePropertyChangeListener(PropertyChangeListener listener) Removes a listener.
void	setMainProject(Project project) Sets the main project.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY_OPEN_PROJECTS

public static final String PROPERTY_OPEN_PROJECTS

Property representing open projects.

See Also:

getOpenProjects(), Constant Field Values

PROPERTY_MAIN_PROJECT

public static final String PROPERTY_MAIN_PROJECT

Property representing main project.

Since:

org.netbeans.modules.projectuiapi/1 1.20

See Also:

getMainProject(), Constant Field Values

Method Detail

getDefault

public static OpenProjects getDefault()

Get the default singleton instance of this class.

Returns:

the default instance

getOpenProjects

public Project[] getOpenProjects()

Gets a list of currently open projects.

Since 1.26, the standard implementation handling the list of opened projects, delays their actual loading. First of all the startup of all modules is finished and only then the projects are loaded and opened on background. As soon as and no sooner before all opened projects are opened, the return value of this method changes and appropriate property change event with PROPERTY_OPEN_PROJECTS is delivered.

Returns:

list of projects currently opened in the IDE's GUI; order not specified

openProjects

public Future<Project[]> openProjects()

Method to track progress of projects opening and closing. As the opening of a project may take long time, and as there can be multiple projects open at once, it may be necessary to be notified that the process of open project list modification started or that it has finished. This method provides a future that can do that. To find out that the list of open projects is currently modified use:

 assert openProjects().isDone() == false;
 

To wait for the opening/closing to be finished and then obtain the result use:

 Project[] current = openProjects().get();
 

This result is different that a plain call to getOpenProjects() as that methods returns the current state, whatever it is. While the call through the future awaits for current modifications to finish. As such wait can take a long time one can also wait for just a limited amount of time. However this waiting methods should very likely only be used from dedicated threads, where the wait does not block other essencial operations (read: do not use such methods from AWT or other known threads!).

Returns:

future to track computation of open projects

Since:

1.27

open

public void open(Project[] projects,
        boolean openSubprojects)

Opens given projects. Acquires ProjectManager.mutex() in write mode.

This method is designed for uses such as a logical view's Libraries node to open a dependent project. It can also be used by other project GUI components which need to open certain project(s), e.g. code generation wizards. This should not be used for opening a newly created project; rather, WizardDescriptor.InstantiatingIterator.instantiate() should return the project directory. This should also not be used to provide a GUI to open subprojects; CommonProjectActions.openSubprojectsAction() should be used instead.

Parameters:

projects - to be opened. If some of the projects are already opened these projects are ignored. If the list contain duplicates, the duplicated projects are opened just once.

openSubprojects - if true subprojects are also opened

Since:

org.netbeans.modules.projectuiapi/0 1.2

open

public void open(Project[] projects,
        boolean openSubprojects,
        boolean showProgress)

Opens given projects. Acquires ProjectManager.mutex() in write mode.

This method is designed for uses such as a logical view's Libraries node to open a dependent project. It can also be used by other project GUI components which need to open certain project(s), e.g. code generation wizards. This should not be used for opening a newly created project; rather, WizardDescriptor.InstantiatingIterator.instantiate() should return the project directory. This should also not be used to provide a GUI to open subprojects; CommonProjectActions.openSubprojectsAction() should be used instead.

Parameters:

projects - to be opened. If some of the projects are already opened these projects are ignored. If the list contain duplicates, the duplicated projects are opened just once.

openSubprojects - if true subprojects are also opened

showProgress - show progress dialog during the open, will run asynchronously in that case.

Since:

1.35

isProjectOpen

public boolean isProjectOpen(Project p)

Finds out if the project is opened.

Parameters:

p - the project to verify. Can be null in such case the method return false

Returns:

true if this project is among open ones, false otherwise

Since:

1.34

close

public void close(Project[] projects)

Closes given projects. Acquires ProjectManager.mutex() in the write mode.

Parameters:

projects - to be closed. The non opened project contained in the projects array are ignored.

Since:

org.netbeans.modules.projectuiapi/0 1.2

getMainProject

public Project getMainProject()

Retrieves the current main project set in the IDE.

Warning: the set of usecases that require invoking this method is limited. MainProjectSensitiveActions should be used in favour of this method if possible. In particular, this method should not be used to let the user choose if an action should be run on the main vs. the currently selected project.

As a rule of thumb, any code outside of the project system infrastructure which behaves differently depending on the choice of main project should be reviewed critically. All functionality of a project ought to be available regardless of the "main project" flag, which is intended only as a convenient shortcut to permit certain actions (such as Run) to be invoked from a global context on a preselected project.

Returns:

the current main project or null if none

Since:

1.11

setMainProject

public void setMainProject(Project project)

Sets the main project. Should not generally be called programmatically; an exception would be when renaming a main project.

Warning: the set of usecases that require invoking this method is very limited and should be generally avoided if possible. In particular, this method should not be used to mark a project just created by the New Project wizard as the main project.

Parameters:

project - project to set as main project (must be open), or null to set no project as main.

Since:

1.11

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Adds a listener to changes in the set of open projects. As this class is a singleton and is not subject to garbage collection, it is recommended to add only weak listeners, or remove regular listeners reliably.

Parameters:

listener - a listener to add

See Also:

PROPERTY_OPEN_PROJECTS

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Removes a listener.

Parameters:

listener - a listener to remove

getActiveProjectGroup

@CheckForNull
public ProjectGroup getActiveProjectGroup()

return the currently action project group

Returns:

can be null if no group is active

Since:

1.61

addProjectGroupChangeListener

public void addProjectGroupChangeListener(@NonNull
                                 ProjectGroupChangeListener listener)

add listener to changes in active project group

Parameters:

listener -

Since:

1.61

removeProjectGroupChangeListener

public void removeProjectGroupChangeListener(@NonNull
                                    ProjectGroupChangeListener listener)

remove listener to changes in active project group

Parameters:

listener -

Since:

1.61