ProCol Client User's Guide

Up

Table of Contents



Requirements

The software requirements for the ProCol Client are Java 1.4.0 or higher and jEdit 4.2pre11 or higher. Minimum system specifications are a Pentium II-class CPU with 64 MB of RAM. Minimum recommended screen resolution is 800x600 pixels.



Installation

To install the client, the ProCol.jar file must be copied to to the jars subdirectory of either the directory in which jEdit is installed, or the user settings directory. The user settings jars directory is usually /home/username/.jedit/jars/ for *nix or C:\Documents and Settings\username\.jedit\jars\ for Windows.) If you are unable to determine the correct place to put the jar file, please see the Plugin sections in the jEdit user's guide for more information about manual installation of Plugins.

After copying the jar file, the plugin will need to be loaded. This is done automatically when jEdit is started. If jEdit is currently running when the plugin is installed, you can go to Plugins>Plugin Manager and check the corresponding box for ProCol (uncheck and recheck the box if upgrading from a previous version of ProCol), or you also may simply restart jEdit.



Starting the Client

Once the client is installed and loaded, to open the client interface, go to Plugins>ProCol>Client>ProCol Client. This will load the window for the client. See below for more information on using the client interface.



Interface Introduction

The interface is broken into three major parts. At the top of the window is a set of buttons for connecting/disconnecting, project operations, and plugin options and help. Below this is the project file tree and related buttons. Next is the user list and communication and management buttons. There is also a network progress bar at the bottom of the interface.

GUI Overview

Dockable Windows

Dockable windows are a feature provided by jEdit which lets plugin windows be docked to any of the four sides of the screen.

Various jEdit and plugin windows can be docked into the view for convenience. Dockable windows have a popup button in their top-left corner. Clicking this button displays a menu with commands for docking the window in one of four sides of the view.

On each side of the text area where there are docked windows, a strip of buttons is shown. There is a button for activating each docked window, as well as a close box and a popup menu button, which when clicked shows a menu for moving or undocking the currently selected window. The popup menu also contains a command for opening a new floating instance of the current window.

The commands in the View>Docking menu move keyboard focus between docking areas.

Dockable windows can also be configured in the Docking pane of the Utilities>Global Options dialog box.

ProCol windows that are dockable include:

  • ProCol Client (Main window)
  • Private Messages
  • Public Messages
  • Todo List
  • Bug List
  • Checkin Panel
  • Upload Panel
  • Server Status
  • Server Admin
  • Server Log

Dockable Windows
An example of dockable windows. ProCol is docked to
the right, and the Bug List is docked to the top.

Dockable ProCol windows are arranged with the optimal layout for their docking posistion. Windows at the sides are arranged vertically, and windows at the top or bottom are arranged horizontally.

Please see the latest jEdit documentation for additional or updated information about using dockable windows.



Connecting

To connect to a server, you click the Connect button located at the top of the ProCol Client window or select Plugins>ProCol>Client>Connect/Disconnect from the jEdit menu bar. When this is selected, the Connect dialog will be displayed and the address/IP and port the server is running on can be inputted. Clicking OK will connect the client to the server.

Connect to Server
The Connect Dialog

After the client has been connected to the server, you will be required to authenticate. Input your user name and password as defined on the server. Clicking OK will authenticate you with the server. The welcome message from the server is also displayed in this dialog, which may provide the user with some information about the server.

Logging in to Server
The Login Dialog

Once the user has been authenticated on the server, a list of projects available to that user is displayed. Some optional project information may also be displayed here. Select the project you wish to connect to and click OK to join that project.

Select Project Dialog
Select Project Dialog



Working with Files

Files are typically the heart of a project. ProCol provides many functions for working with files in a project. This includes check-out and check-in of files, uploading and creating new files. There is also the ability to grab a current snapshot of the entire project tree, and there is also the ability for server-side operations on files, such as renaming and deleting files.

Checking Out Files

All files related to the project are stored on the server. All files are contained within a single tree, known as the project tree. In order to work on a file, it must first be checked out. Checking out a file sets you as the current owner, preventing other users from modifying that file while you have it checked out. In the same fashion, if another user has a file checked out, you may download a copy of that file, but you may not check it out. Checked out files are displayed in a bold font in the file tree. Holding your mouse over the file name will display who has that file checked out.

To check out a file, the file must be selected. Once a file is selected, right clicking on the file will display a popup menu, and selecting Check Out will check out that file. When a file is checked out, it is downloaded to the client, written to disk, and a buffer is opened within jEdit to allow editing of the file.

It is also possible to check-out multiple files at once. By checking out a directory will recursively check out all files within that directory. It is also possible to select and check out multiple files or directories by using Ctrl or Shift.


Checking In Files

Once a check-out file has been modified and closed, it will need to be checked back in to the server. The Check In Dialog will be displayed with a list of all files currently waiting to be checked-in.

Check in Dialog
The Check In Dialog

The Check In Dialog consists of several parts. On the left is the list of files waiting to be checked-in. On the top right is the new version information. There are three spinners to set the new version number. There are three modes to update the version.

At the bottom right is the changelog information. A note about the current file (i.e. changes made, bugs fixed, etc) can be written in here.

To check in a file, click on the Check In button on the left. This will upload the currently selected file(s) and associated data. Multiple files can be checked-in by using Ctrl or Shift to select multiple files in the list.

If there are no more files to be checked in, the check in window will be closed.


Uploading Files

In order to upload a file or directory to the server, you may right-click on the target directory in the file tree, and select Upload File or Upload Directory from the popup menu. Alternatively, you may select the target directory and click the Upload File or Upload Directory button from the project button bar. To upload a file to the root directory, either right-click in an empty area of the tree, or deselect all files using Ctrl and then click the Upload button.

This will display jEdit's file select dialog. Select the file(s) you wish to upload, and click Choose to select the file(s).

Once a file or a directory has been selected for upload, the Upload Dialog will be displayed with a list of all files currently waiting to be uploaded.

The user interface for uploading files is quite similar to the check in file dialog

The upload Dialog consists of several parts. On the left is the list of files waiting to be checked-in. On the top right is the new version information. There are three spinners to set the new version number. There are three modes to update the version.

Note: When uploading a file, Increment and Absolute have the same effect.

At the bottom right is the changelog information. A note about the file(s) being uploaded can be written in here.

To upload a file, click on the upload button on the left. This will upload the currently selected file(s) and associated data. Multiple files can be uploaded by using Ctrl or Shift to select multiple files in the list.

If there are no more files to be checked in, the upload window will be closed.


Creating New Files

In order to create a new, empty a file or directory on the server, you may right-click on the target directory in the file tree, and select New File or New Directory from the popup menu. Alternatively, you may select the target directory and click the New File or New Directory button from the project button bar. To create a new file in the root directory, either right-click in an empty area of the tree, or deselect all files using Ctrl and then click the New button.

You will be prompted for the name of the file or directory. Enter the name and select OK to create the file or directory.


Download Files

To download a file or directory, select the file(s) from the project tree and right click to display the popup menu. Select Download Copy from the menu, and select the destination on your disk. After you choose the destination, the file(s) will be downloaded from the server.

You can also easily download a current snapshot of the entire project tree by selecting the Download Snapshot button from the project button bar. You will be prompted for the destination, and the entire project tree will be downloaded.


Other File Operations

There are other file operations in the popup menu, Rename, Delete, and File Info.

To rename a file, right click on the file name in the project tree and select Rename. You will be prompted for the new file name. Input the new name and select OK to rename the file.

To delete a file, right click on the file name in the project tree and select Delete. You will be prompted for confirmation. Select Yes to delete the file. You may also delete multiple files at a time by using Ctrl or Shift to select multiple files in the list.

To display information about a file, right-click on the file name in the project tree, and select File Info.

This will display a dialog which displays the file information and version history from the server. Clicking OK will close this dialog.

File Info Dialog
The File Info Dialog


User List

The User List contains a list of all the users who are currently connected to the server. Right-clicking on a user's name will bring up a context popup menu where you can sent a private message or get more information about that user.


User Info

To display information about a user, right-click on the user's name in the User List, which will display the popup menu. Select User Info from the menu to display the user info dialog.

This will display a dialog which displays the user information from the server. Clicking OK will close this dialog.



Communication

There are two methods of communication available with ProCol, private messages and public messages.


Private Messages

Private messages can be used to send messages to one or more users. Only these users will receive the message.

The private message button is located in the button bar below the user list. This button is highlighted in color if there is a new message waiting.

To open the private message panel, click on the Private Messages button in the button bar below the user list. You will see a panel that looks similar to the image below:

Private Message Panel
Private Message Panel

The Private Message Panel consists of three main parts. On the left is the button bar, with buttons for creating a new message, replying to a message, and deleting a message. In the center is a list of all available messages. Selecting a message in the list will display the contents in the rightmost panel.

Creating a new message or replying to an existing message will bring up a dialog similar to below:

Private Message Composer
Private Message Composer

The Private Message composer consists of three areas, a Subject line, a recipient list, and a message area. Entering a subject, recipient(s), and message and clicking Send will sent the message and close the composer. A message can be sent to multiple users by using Ctrl or Shift to select multiple users in the list.


Public Messages

Public messages can be used to send messages to all the users for that project. All the users with access to the open project will receive the message.

The public message button is located in the button bar below the user list. This button is highlighted in color if there is a new message waiting.

To open the public message panel, click on the Public Messages button in the button bar below the user list. This panel is very similar to the Private Message Panel.

The Public Message Panel consists of three main parts. On the left is the button bar, with buttons for creating a new message, replying to a message, and deleting a message. In the center is a list of all available messages. Selecting a message in the list will display the contents in the rightmost panel.

Creating a new message or replying to an existing message will bring up a dialog similar to the Private Message composer, except it does not have a recipient list.

The Public Message composer consists of two areas, a Subject line and a message area. Entering a subject and message and clicking Send will sent the message and close the composer.



Project Management

There are two methods of project management available with ProCol, a bug list and a todo list.


Bug List

The Bug List contains a list of software bugs and issues that need to be resolved. Bugs are composed of a subject, description, due date, assignee, priority, and percent complete.

The bug list button is located in the button bar below the user list. This button is highlighted in color if there is a new bug item waiting.

To open the bug list panel, click on the Bug List button in the button bar below the user list. You will see a panel that looks similar to the image below:

Bug List Panel
Bug List Panel

The Bug List Panel consists of three main parts. On the left is the button bar, with buttons for creating a new bug item, modifying to a bug item, and deleting a bug item. In the center is a list of all available bug items. Selecting a bug item in the list will display the contents in the rightmost panel.

Creating a new bug item or modifying an existing but item will bring up a dialog similar to below:

Bug Item Composer
Bug Item Composer

The Bug Item composer consists of several areas, a subject line, a description area, a due date, an assignee, a priority, and the percent complete. Imputting the information for the bug and clicking Submit will send the information to the server.


Todo List

The Todo List contains a list of things that need to be done for the project. Todo items are composed of a subject, description, due date, assignee, priority, and percent complete.

The todo list button is located in the button bar below the user list. This button is highlighted in color if there is a new todo item waiting.

To open the todo list panel, click on the Todo List button in the button bar below the user list. You will see a panel that looks similar to the bug list panel.

The Todo List Panel consists of three main parts. On the left is the button bar, with buttons for creating a new todo item, modifying to a todo item, and deleting a todo item. In the center is a list of all available todo items. Selecting a todo item in the list will display the contents in the rightmost panel.

Creating a new todo item or modifying an existing but item will bring up a dialog similar to the bug list panel.

The Todo Item composer consists of several areas, a subject line, a description area, a due date, an assignee, a priority, and the percent complete. Imputting the information for the todo and clicking Submit will send the information to the server.




Working with Projects

Besides working with files, communication, and project management tools, there are some miscellaneous tools to work with projects.


Project Info

To display information about the currently opened project, click on the Project Info button in the top button bar of the ProCol Client window, or select Plugins>ProCol>Client>Project Info from the jEdit menu bar.

This will display a dialog which displays the project information from the server. Clicking OK will close this dialog.


Changing Projects

To change the currently opened project, click on the Change Project button in the top button bar of the ProCol Client window, or select Plugins>ProCol>Client>Change Project... from the jEdit menu bar.

The Select Project dialog will be displayed (this is the same dialog that was displayed when first connecting to the server). Selecting a project and clicking OK will close your current project and open the new project. Selecting cancel will abort the project change, and you can continue working in your currently opened project.



ProCol Options

ProCol Options are used to configure the plugin's settings To open up the options interface for ProCol, click on the options button in the top button bar of the ProCol Client window. This will display jEdit's plugin options interface and load the ProCol option pages.

Alternatively, you may go to Plugins>Plugin Options in the jEdit menu bar, and select ProCol>Client Options or ProCol>Server Options in the plugin list.

Note: Options are not currently implemented within the jEdit options interface. Currently, all configuration must be done by manually editing the properties files.



ProCol Help

Online help is available for ProCol. (In fact, chances are you are looking at it right now). To open up the help interface for ProCol, click on the help button in the top button bar of the ProCol Client window. This will display jEdit's help interface and load the ProCol help pages.

Alternatively, you may go to Help>jEdit Help in the jEdit menu bar, or press F1, to load the jEdit help, and then select Plugins>ProCol in the contents tree.



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 is contained in the file COPYING.DOC.txt included with ProCol.

(c) 2003-2004 Justin Dieters