Project Viewer plugin

Version 3.5.2 (May 31 2013)

Dale Anson

Kevin Burton

Stefan Kost

Matthew Payne

Marcelo Vanzin

Calvin Yu

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no "Invariant Sections", "Front-Cover Texts" or "Back-Cover Texts", each as defined in the license. A copy of the license can be found in the file COPYING.DOC.txt included with jEdit.


Table of Contents

Chapter 1. Presentation

The Project Viewer plugin allows to define groups of files as projects.

What is a project?

A project is a group of files. It has a name, a root directory, and an optional URL Root, along with other options that can be made available by other plugins.

Files in a project are not restricted to the project root: any file can be added to the project (or to any directory in the project), allowing you to organize your files however you find most convenient, independently of the file system layout. The project root and the files and directories below it have a special treatment not given to others, though.

If a project is intented for website development, setting the URL Root will enable project files to be launched in a web browser. Suppose the project root also correlates to the URL "http://localhost/myproject/" currently running on a web server, launching the file "hello.jsp" will launch the web browser with the URL "http://localhost/myproject/hello.jsp".

Chapter 2. Using the Project Viewer plugin

The plugin interface consists of a a menu containing the currently available projects (accessible through the button labeled with the current active node), and the project's views.

To open a Project Viewer window, you'll need to choose the "Open Project Viewer" action from the plugin's menu. Optionally, you can go to the Global Options dialog in jEdit, and dock the window in your favorite position (in the "Docking" tab). Note that activating a project or group using the plugin menu will not open a Project Viewer window if one is not already opened.

Creating your first project

Create a project by right-clicking on a project group and choosing "Add Project", or navigating the project tree in jEdit's "Plugins -> Project Viewer" menu.

Organizing Your Projects

Project Viewer allows you to organize your projects into groups. You can create as many groups as you with in an hierarchical manner, by using the "Add group here" command in the tree's context menu, or choosing the "New group here" entry from under the desired group in the projects menu.

As with projects, it is possible to have groups as the root of the tree shown in the dockable window. For this, just choose a group from the projects menu to make it active. Some plugin functionality is not available when in this mode.

You can also move projects and groups to other locations in your group hierarchy by using the "Move to..." command in the tree's context menu and choosing the desired destination from the displayed menu.

Switching projects with keyboard

As you create more and more projects, you will want to be able to switch between them without using the mouse. Project Viewer offers many keyboard-friendly ways of switching projects.

  1. If you want to use standard Swing shortcuts and arrow keys to navigate through the Project tree, you should also bind Project Viewer actions Open Parent Group and Open Group or Project to keyboard shortcuts (alt-up and alt-down suggested). While you are there, don't forget to bind a shortcut for ProjectViewer itself.

  2. Each project and group gets its own "direct switch" action. You can bind these actions to keyboard shortcuts by selecting the Project Viewer: Project Actions action set from the Global options -> ShortCuts panel -> Edit shortcuts: combobox.

  3. The FastOpen plugin offers more convenient and/or mouse-free ways of switching between files and projects, and is an extension to ProjectViewer.

The Project Views

There are four possible views of the files on a project: the "Folders" view, which shows the files as if in a file manager, organised in directories. The "Files" view, which shows all the project's files in a flat list. The "Working Files", which shows the project files currently opened in jEdit. And the "Compact View", which compresses subdirectories into top-level nodes, showing a structure similar to the java package naming.

The files in the different views are colored according to the patterns and colors you have choosen for the filesystem-browser. Furthermore currently open files are highlighted by underlining their names.

You can interact with the project tree in several ways:

  • Double clicking on a file will cause it to be opened in a jEdit buffer. If the file is already open, then ProjectViewer follows the FileSystemBrowser configuration option to decide whether to close it or not.

  • Middle-clicking on a file does the same as double-clicking, except it will always close open files.

  • The right mouse button shows a context menu with options related to the current selection on the tree, allowing you to remove files or directories from a project, deleting them from the disk, or rename them, among many other options.

  • Dragging a file from the trees and dropping it on jEdit's text area will cause the file to be opened.

Importing Files

In the import dialog (available by choosing "Add files" from the right-click menu), you can choose any files to be imported to the selected node (the one where you clicked to get the context menu). The same filters available when doing the initial import for the project are available in the file chooser.

You may choose any files and directories to import, even files and directories that are not "children" of the selected node in the file system layout. This allows you to organize your files in any way you want. You may even enter the name of a non-existant file in the file chooser: it will be treated as a directory, and even though the directory does not exist on disk, you'll have the same functionality for it as you have for other directories in your project.

The file import dialog is a standard jEdit VFS file chooser with a few added options to control the behavior of the import process. These options are:

  • Traverse directories: if a directory is chosen to be imported, this option will cause all files and directories under the chosen directories to also be imported, as long as they fit the chosen filter.

  • Flatten file paths: when traversing directories, you may choose to import all the files into a single node, insted of generating a directory tree.

  • Keep Project Tree: if you choose to import files several leves under the chosen node, this option will make all parent nodes be added to the project too, making the project's layout follow the filesystem layout. This is selected by default.

  • Import into new node: this will create a new node under which you are importing files, and all newly added files and directories will be placed under this new node.

  • Filter settings: when traversing directories, you may choose from some existing file filters to choose the files to be imported, or create your custom file filter on the fly by providing globs for files to be included and directories to be ignored. For more information about the glob syntax, see "Import Options" under the "Customization" chapter.

Commands available in the context menu

The context menu provides context-sensitive options based on the current tree selection. The following commands can be found in the context menu (some of them have already been explained above):

  • Add files: pops a file chooser from where you can choose any files or directories to import. These will be imported into the selected node, disregarding the file system layout. If importing directories, you'll be prompted if you want to do it recursively using one of the available filters.

  • Add files from VFS: lets you select files from a jEdit VFS (Virtual File System), such as FTP. If you choose local files, ProjectViewer will add standard files instead of VFS files. The functionality of VFS files in ProjectViewer is rather limited when compared to standard files.

  • Re-import files: this command will remove all files and directories below the project root, and re-read the file structure from disk according to the selected filter (which can be chosen from the dialog that pops up). It will also analyze directories not under the project root: it will re-import existing directories and remove stale files from "virtual" directories.

  • Update VCS Status: this command is available only if the project has specified a version control system. This command forces an update of the version control status for every file in the project. This is useful for projects that may have files that are updated outside of jEdit.

  • Remove from project: this will remove the selected node from the project to which it belongs. It is also possible to remove multiple nodes at once.

  • Delete from disk: this is only shown for files to which you have write permission. Choosing it will cause the files to be deleted from disk and removed from the project.

  • Rename: this will prompt you for a new name for the selected node. If you check the "Don't change name on disk" option, only the node name on the tree will be changed; the file on disk will keep its current name.

  • Archive project: this will prompt you for a file name. A JAR archive will be created containing all files below the project root.

  • Preview in browser: this will open the file in the configured web browser. If a project URL is set, files below the project root will be redirected to the given URL; in other cases, the "file://" protocol will be used. The part of the file path corresponding to the project root will be removed when opening the file relatively to the project URL.

  • Open with: this will open the selected file in a configured application associated with its extension (configured in the Project Viewer's plugin options). If no application is configured for the selected file, selecting this option will prompt you to choose an application.

  • Node Properties: this shows a dialog with information about the selected node. For example, for file nodes, you can get information collected from the filesystem.

Using PV commands from jEdit

Some commands are also available as jEdit actions so that shortcuts can be assigned to them. You can check all the possible commands available as actions by going to the "Shortcuts" panel in the jEdit options dialog, and selecting the ProjectViewer plugin.

When executing a command using a shortcut, you may notice that sometimes no action is performed and an error message appears in the status bar. This means that the action is not available for the current selection in the tree. To check which actions are available for the selected node(s), check the context menu by clicking the node with the right mouse button.

Third party plugins commands

Project Viewer can be extended by other plugins; they can add properties to a project and define new actions for nodes in the tree. Consult each plugins documentation for information about possible commands available for the Project Viewer plugin.

For developers go to chapter Developer Documentation to get some starting help fo how to cooperate with the Project Viewer plugin.

Chapter 3. Customization

Several options are configurable from the jEdit options dialog. There are options to control the GUI of the plugin, and internal behaviour when executing several actions. The options are:

General Behaviour Options
  • Use external applications by default: if selected, files that are open from the tree (by either double-clicking or middle-clicking) will be opened using the external application configured for the file's extension, if any. If no application is found, it will be opened in jEdit. You can still open the file in jEdit by dragging the file node onto jEdit's text area. When opening in an external application, you'll lose support for auto-closing the file on project file, auto-loading the file when the project is re-activated and the file node won't be underlined, indicating it is opened..

  • Close files on project change: if selected, files from the current project that are opened in jEdit will be closed when you switch to another project.

  • Remember open files: if selected, files opened in the current project will be re-opened when you select the same project in a later moment, even between different jEdit sessions.

  • Use variable-prefixed paths when storing project data: If selected, will use paths prefixed with environment variables, if appropriate variables are found in memory. This makes it possible to move project data from one machine to another when the absolute paths differ, but the paths relative to a variable remain the same.

  • Auto-remove non-existant files from project: if selected, each file in the project is verified to exist when the project loads. If the file does not exist, it is removed from the project.

  • Ask to import new files: if "Always" is selected, every time you save a file located below the active project's root, and the file is not yet part of the project, you'll be asked whether you want to import it. Selecting "Once per session" will ask only one time during the time the current project stays active. "Never" will disable this feature. "Auto import" will automatically add to the project any saved files which are under the project root and are not currently part of the project.

GUI Options
  • Show toolbar: whether to show the plugin's toolbar or not. The toolbar is automatically hidden when no tree is selected for showing, regardless of this option.

  • Show folders tree: if the "Folders" tree view should be shown.

  • Show files tree: if the "Files" tree view should be shown. Disabling this view can greatly improve performance when your projects have many files.

  • Show working files tree: if the "Working Files" tree view should be shown.

  • Show all open files: if the "Working Files" tree is shown, checking this will also show all open files in the current View, whether the files are in the project or not.

  • Show compact tree: whether the "Compact" tree view should be shown.

  • Show filtered tree: whether the "Filtered" tree view should be shown.

  • Use system icons for files: instead of using jEdit's icons, uses the system provided icon for each individual files. The jEdit icon will still be used when the file is opened. On some systems, the system icons may not be accessible from Java, so this option may not work as expected.

  • Show project (or group) name in the view's title bar: if selected, the jEdit window title will be updated with information about the currently active project or group in that window.

  • Follow active node in tree: this option will make PV automatically select the node corresponding to the active buffer as you switch between buffers.

Import Options

This controls the behaviour of the "Import settings" filter available when importing files.

  • Files to include: a list of globs that match files you want to include in a project (e.g., "*.html", "*.java", "README*"). If you want to exclude files from the automatic import, prepend the glob with the "!" character (e.g., "!*.class").

  • Directories to ignore: space-separated list of globs to match directory names to ignore when doing automatic import of files. No files within directories whose names are listed here will be imported.

Editing the context menu

ProjectViewer provides an interface similar to jEdit's context menu editor, where you can add actions to be displayed in the trees' context menus. You can't remove the default entries in the context menu, but any action available to jEdit can be added. It's important to notice that adding an action to the context menu won't make it "Project Viewer aware": unless the action is specifically written to interface with ProjectViewer, it will work the same way as it would if executed from any other place (such as the jEdit toolbar or menu).

File Associations

If the option "Use Desktop File Associations" is checked, then the desktop's chosen application will be used to launch a program on the selected file in ProjectViewer. Otherwise, The "External Applications" option pane can be used to register applications you want to use for specific file type, accessible through the "Open with..." context menu command for files. Just add a file name glob and choose the application you wish to use for that entry.

Filtered View

The filtered view allows you to group files according to their names. To create a filter, go to the Plugin Options and choose the "Filtered view" pane, or go to the project properties dialog and choose the "Filtered view" pane, to create project-specific filters.

To create a filter, provide a file name glob (see jEdit's documentation for the supported glob syntax) and a name for the filter. If the "Show filtered tree" option is enabled, a new "virtual directory" with the filter name will be available in the "Filtered" tab of the ProjectViewer window, containig all file names that match the glob. Files that match more than one filter will be listed several times in this view.

Chapter 4. Developer Documentation

There is comprehensive documentation included with the source distribution in Javadoc format. Just download the source from the jEdit GIT repository and create the documentation by executing the "javadoc" Ant task in the Project Viewer directory. Documentation will be created under the directory "build/docs/javadoc". Or access the bundled documentation.

Among many classes and methods declared as public, the majority should not be called from outside projectviewer package. They are declared public only because the main package consists of several subpackages and these classes and methods must be accessible between these packages. Safely used may be the following apis:

  • Types exposed through events

  • Constructions used in actions.xml

Before using a particular method or class, refer to its javadoc. An index of public api is being created in javadoc of projectviewer.PVActions class.

The Project Viewer source also contains a second plugin that is used for debugging purposes. This plugin uses all the extension APIs provided by ProjectViewer to add extra functionality. The source for this plugin is available in the "pvdebug" directory in the source tree; you can use that source as an example of how to code your extensions.

External plugins can interact with the Project Viewer plugin in various ways:

  • By providing project specific properties: properties

  • By creating new node types: nodes

  • By creating node-specific actions: actions

  • By listening to Project Viewer events [1]

Common task for interacting with projectviewer
Checking if projectviewer is available

The method described here requires a jEdit with version > 4.2preX.

EditPlugin pv = jEdit.getPlugin("projectviewer.ProjectPlugin", false);
if (pv != null) {
   // we can use the projectviewer plugin
}
        
Getting the project the a given file belongs to
ProjectManager pm = ProjectManager.getInstance();
// then use java.util.Iterator getProjects();
// and foreach project use VPTNode node=prj.getChildNode(java.lang.String path);
        
Getting the project of the given view
VPTProject prj = ProjectViewer.getActiveProject(org.gjt.sp.jedit.View aView);
ProjectViewer pv = ProjectViewer.getViewer(org.gjt.sp.jedit.View view);
        


[1] For details on how to do this, check the package summary for projectviewer.Event in the javadocs.

Chapter 5. Troubleshooting

Large projects

Large projects can take some time to load, especially over a network connection if the "delete non-existant files" configuration option is enabled. This is due to asking whether the file exists for each file in the project, which can be slow in some systems.

Multiple Viewer in same jEdit View

jEdit allows multiple instances of the same dockable for the same view. Project Viewer does not support this feature and will issue an error message if you try to open two Project Viewer windows in the same view.

Chapter 6. License

The source code is distributed under the GPL. Please see http://www.fsf.org/copyleft/gpl.html

Chapter 7. Feedback

The preferred way to send bug reports is to use the Sourceforge Plugin Bugs Tracker . Please start the report subject with the text "ProjectViewer:".

You can also write to:

Chapter 8.  Changelog

For the full changelog, click here.

Chapter 9. Credits
  • ProjectViewer was previously (up to 1.0.2) maintained by Calvin Yu

  • ProjectViewer was originally developed Kevin A. Burton