Control Panel

This is the top-level window that contains top-level menus, the message window, and if virtual desktop mode is on, the browse/debug/find/workbench window and the virtual desktop(s).

Each virtual desktop may contain code editing windows, CPG diagram windows, viewer canvas windows, and UML windows. A "window bar" which by default is at the bottom of each virtual desktop, shows the windows it contains, and allows any one to be selected, minimized, maximized, etc. If Settings > Desktop > Open Desktop Windows Maximized is on (which it is by default), then each virtual desktop functions much like a tab pane, and the window bar like it's tabs. If maximized desktop windows are off, then each virtual desktop functions like a restricted OS desktop, and the window bar somewhat like the Windows taskbar.

Initially there is one virtual desktop. The number and layout of virtual desktops can be changed using View > Desktop Layout or with a button in the group at the bottom left of the control panel.

Buttons on the window bar may be reordered by dragging them. Dragging a button to another virtual desktop will move it's associated window to that desktop.

File > Escape Virtual Desktop will move a window from the virtual desktop to a free-floating frame. From there, File > Enter Virtual Desktop will move it back in. This can also be done using a button in the group at the lower left of the control panel and floating frame. If Settings > Desktop > Virtual Desktop is turned off, the left and bottom panes of the control panel and all windows in virtual desktops will become free-floating, and there will be no virtual desktops. Turning it back on will reverse this process.

The documentation below shows menu items that appear when no windows are open. For menus that are specific to a particular type of active window, see CSD Window, UML Window, or CPG Window.

• File Menu
• Edit Menu
• View Menu
• Project Menu
• Settings Menu
• Tools Menu
• Window Menu

• Shortcut Keys and Mouse Actions
• Message Bar

• Browse Window
• Project Window
• Find Window
• Debug Window and Workbench
• Interactions Window
• Message Window

---

File Menu

New - opens an empty CSD window for the selected language. Recently opened and currently open file types will appear under the main menu; other file types will be under the Other submenu. The Choose menu will open a dialog that allows you to open one or more files for a selected language. This dialog is also accessible through Ctrl-N.

Open - brings up an open file dialog.

Sync All - checks file modification times for all files open in jGRASP with those on disk. For each file that has been modified outside of jGRASP, you are given the option of reloading the file from disk or continuing to use the version being edited. If you choose not to reload, the next check will report a modified file only if there is an additional modification. A save operation, however, will give an external modification warning even if there is not an additional modification when the file has been modified outside of jGRASP.

Close All - closes all CSD Windows. You will be warned and given a chance to cancel if modified files exist.

Save All - saves files in all CSD windows.

Recent Files - allows recently closed files to be re-opened.

Workspace - allows switching the workspace and editing workspaces. A workspace includes the currently open projects and windows, as well as workspace-level settings. Workspaces in jGRASP are named rather than being stored in a user-specified file (as is done on other common IDEs).

Exit jGRASP - quits the application. If a compile process is active and there are modified files, this will not be allowed, since the old files are backed up before compiling, and restored afterward - this is not a concern if the Auto Save setting is checked (it is checked by default), in which case all files are saved before compiling.

---

Edit Menu

Search Multiple Files - brings up the multi-file search dialog.

---

View Menu

Desktop Layout - allows the selection of a single or multiple desktop layout (number of rows and columns). Each desktop serves as either a tab pane or virtual desktop containing the open files and other windows, depending on whether desktop windows are maximized or not.

Toolbars - allows the jGRASP interface to be configured with a single toolbar, separate toolbars for each window, or no toolbars. Windows that are outside the virtual desktop(s) will always have a separate toolbar, unless the mode is set to None.

Visible Toolbar Groups (CSD Window Only) - allows the toolbar icons to be shown or hidden by category.

Toolbar Icon Size - allows the size of the toolbar icons to be changed, either to a relative or absolute size.

Toolbar Buttons - allows the jGRASP interface to be configured so that toolbar buttons show icons only, text only, or both icons and text. This applies to most toolbars in jGRASP.

Messagebars - allows the jGRASP interface to be configured with a single messagebar, separate messagebars for each window, or no messagebars. Windows that are outside the virtual desktop(s) will always have a separate messagebar, unless the mode is set to None.

Menus - allows the jGRASP interface to be configured with a single menu or separate menus for each window. Windows that are outside the virtual desktop(s) will always have a separate menu.

---

Project Menu

Note that any operation that closes a project will save it first. It is not possible to discard changes to a project (unless jGRASP crashes or is killed).

Project operations apply to the project associated with the currently active window.

New - allows you to create a new empty project, a new Java project with subdirectories, or a new J2ME (Java 2 Micro Edition) project.

Open - allows a saved project to be opened.

Close - closes the project.

Close All - closes all open projects.

Save - saves modifications to the project immediately. This is never necessary, except as protection against a crash.

Rename - allows a project to be renamed.

Recent Projects - allows recently closed projects to be opened.

Add Files - opens a dialog that allows you to add files to the active project. This dialog allows files to be added with absolute paths or paths relative to the project file location (if the project is named and the file(s) are on the same file system (drive) as the project file). The relative paths are also platform independent. Using relative paths allows you to move your project to another location or system.

Import Files (J2ME projects only) - similar to Add Files, except that the files are copied into the appropriate directory of the J2ME project.

Remove Selected Files From Project - remove any files selected in the project window. Also removes any project documentation corresponding to Java source files that are removed.

Generate/Update UML Class Diagram - Brings up a UML window for the project and updates the UML diagram.

Generate Documentation - brings up a dialog that allows you to generate project documentation for Java.

Show Documentation - displays the documentation for the active project, if any. Currently, only Java documentation is supported.

Create MIDlet Package (JAR/JAD) - brings up a dialog for creating a JAR/JAD package for a J2ME project.

Create JAR or Zip File for Project - brings up a JAR/zip creation dialog for the project.

JAR/Zip Extractor - brings up a JAR/zip extractor dialog.

---

Settings Menu

Desktop - settings that deal with the appearance and functionality of the desktop.

Auto Save - if on, modified files are saved before a compile operation. Otherwise, modified files are temporarily saved before a compile operation, while the on-disk versions are backed up before, and restored after, the operation.

Auto Compile - if on, Java files and projects will be compiled if necessary before a run or debug operation.

Verify on Save - if on, files will be verified after saving. That is, they will be read back in and compared to that data that was written.

Auto Sync - if on, file modification times will be checked every time the control panel is activated. You would almost certainly not want this on if you are in a focus-follows-mouse environment (if you are using Windows, you are not in a focus-follows-mouse environment). See Sync All.

Verbose Messages - if on, compile, run, and CSD generation functions will give detailed messages about their operation, and for many messages full path names will be shown instead of simple file names. You can also use the middle icon on the control panel message bar to switch between verbose and short message modes.

Documentation Settings - brings up a dialog that allows you to change settings related to the display of documentation. This contains the following settings:

Colors - opens a CSD settings dialog for the current workspace, and selects the Colors tab, which allows changing colors for each token type in the CSD and message windows, as well as the CSD window background color and CSD color.

Font - opens a CSD settings dialog for the current workspace, and selects the Font tab, which allows changing the bold and italic state of the font for each token type in the CSD and message windows, as well the font, font encoding, CSD and message window font sizes, and global font scale.

CSD Window Settings

Compiler Settings - opens a CSD settings dialog for the current workspace, selected project, or active file, and selects the Compiler tab, which allows changing and editing compiler environments.

PATH / CLASSPATH - opens a CSD settings dialog for the current workspace or selected project, and selects the PATH tab, which allows changing the PATH and CLASSPATH for compiling and running.

Plugin Paths - opens a CSD settings dialog for the current workspace, and selects the Plugin Paths subtab of the PATH tab, which allows changing the directories where viewer and tool plugins may be located.

Print Settings - opens a print settings dialog for the current workspace, selected project, or active file.

Java Debug Settings - opens a dialog that allows changing the properties of the integrated Java debugger.

J2ME Settings - opens a dialog that allows changing the global settings that apply to J2ME projects.

Administrator CSD Window Settings (Administrator Only) - opens a CSD settings dialog for the administrator settings, and selects the CSD tab, which has settings that change CSD generation and editing properties.

Administrator Compiler Settings (Administrator Only) - opens a CSD settings dialog for the administrator settings, and selects the Compiler tab, which allows changing and editing compiler environments.

Administrator Print Settings (Administrator Only) - opens a print settings dialog for the administrator print settings.

jGRASP Startup Settings (Windows and macOS Only) - allows you to choose which "java" is used to run jGRASP, the maximum memory available to jGRASP, and other startup settings. These will take effect the next time jGRASP is started. Note that the "java" used to run jGRASP is not necessarily the same one used to compile and run Java programs. To change the "java" used for compiling and running programs, us Settings > PATH / CLASSPATH.

Look And Feel - allows the look and feel to be changed. After a change, the color, size, and alignment of some interface elements may be slightly off due to Swing bugs in some versions of Java. Quitting and restarting jGRASP will correct this.

Check for New Version - allows you to turn automatic checking for new jGRASP versions on or off, or to check for a new version immediately. This automatic check setting is permanent, while rejecting an update notification with "Don't remind me again" will only last until the next release notification. Note that minor updates may not trigger an automatic update notification, but a manual check will alert you to any newer available version.

Usage Reporting - allows you to turn usage reporting on or off. When usage reporting is on, jGRASP will send data about the number of times various jGRASP features are used to us, once per day at most.

---

Tools Menu

In addition to the items listed below, a submenu for each tool plugin will also appear on this menu.

Regular Expression Tester - pops up a testing tool for Java regular expressions, which are used in compiler error formats.

System Info - displays information about the operating system and Java version under which jGRASP is running, and similar information.

Run Garbage Collector - frees unused memory (in jGRASP itself) immediately on most systems.

Reload Plugins - reloads the debugger viewers and tool plugins. In a future version of jGRASP, APIs will be provided so that users can easily develop their own viewers and tool plugins. This function will cause those plugins to be reloaded after changes are made, so that plugins can be modified and tested while jGRASP is running.

Compile Multiple Java Files - brings up a dialog that allows compiling a group of Java files.

---

Window Menu

Refresh Window - causes the main window to be repainted.

Cascade - lays out the windows in the virtual desktop(s) in a cascade.

Cascade and Resize - lays out the windows in the virtual desktop in a cascade and sets them to their default sizes.

Close All - this submenu allows closing all open files, or all open files of a certain type.

The rest of the items represent currently open CSD windows, and allow you to pop them up. An asterisk following a file name indicates that it is modified.

---

Shortcut Keys and Mouse Actions

Most shortcut key combinations are menu accelerators that are shown on their associated menu buttons. The following actions that affect font zoom are not available from menus. Note that on Mac systems, the Cmd key is used in place of Ctrl.

Font Scale for All Windows

These change the font scale for all windows, menus, buttons, etc. For individual desktop windows, this global scale is combined with possible individual window scaling.

Ctrl-plus - increases the global font scale by approximately 10%.

Ctrl-minus - decreases the global font scale by approximately 10%.

Ctrl-zero - resets the global font scale to 1.0, and resets the font scale for all individual windows to 1.0.

Ctrl-Alt-mouse_wheel - increases or decreases the global font scale.

Alt- Trackpad Pinch Zoom - on some systems, a trackpad two-finger "pinch zoom" while the "Alt" key is held down may also be used to change the font scale for the window in focus.

Font Scale for Desktop Windows

These change the font scale for the desktop window (code editing window, CPG window, etc.) that is in focus, or if no desktop window had focus, the font scale for the message and I/O windows.

Ctrl-Shift-plus - increases the font scale by approximately 10% for the window in focus.

Ctrl-Shift-minus - decreases the font scale by approximately 10% for the window in focus.

Ctrl-Shift-zero - resets the font scale to 1.0 for the window in focus.

Ctrl-mouse_wheel - increases or decreases the font scale for the window in focus.

Trackpad Pinch Zoom - on some systems, a trackpad two-finger "pinch zoom" may also be used to change the font scale for the window in focus.

---

Message Bar

The message bar at the bottom of the control panel displays the current state of jGRASP (debugging, running, etc.) and information about the window that currently has focus (if jGRASP is configured for multiple message bars, then that information will appear on the message bar for that window instead). On the left side of the message bar, there are several shortcut buttons described below.

Escape Virtual Desktop - moves the selected window from a virtual desktop to a free-floating frame. If multiple message bars are on, this button will appear on the message bar for the individual window.

Control Panel Layout - allows switching the left pane of the control panel to full height, or the message pane to full width.

Desktop Layout - allows cycling through all possible desktop layouts. This controls the number and layout of virtual desktops.

Verbose Messages - toggles verbose message mode. When this is on, compile, run, and CSD generation functions will give detailed messages about their operation, and for many messages full path names will be shown instead of simple file names.

Open Maximized - toggles open maximized mode. When this is on, any window opened in the virtual desktop(s) will be initially maximized. This means the virtual desktop will behave like a tab pane.

---

Open File Dialog

A dialog for opening files.

Filters for the languages supported by jGRASP are provided, as well as the "all files" filter. Note that language filters classify files based on the extension only if they have not been opened in jGRASP before. Once a file is opened, jGRASP remembers that language. The default language for files with a ".h" extension can be set to C++ or C only (not both) by changing the extension settings for C or C++ (see settings).

You can also type a list of extensions into the Filter Extensions field to filter by extensions. These must be separated by whitespace, and can start with ".", "*.", or nothing. For example: "*.c *.cpp", ".c .cpp", and "c cpp" will all show only files that end in ".c" or ".cpp". Note that you can do the same thing by entering filter expressions in the File Name field, such as "*.c" or "*.c|*.cpp" .

The Text / Binary radio buttons allow the file to be opened in text mode (UNIX, DOS, and Mac. line terminators accepted) or binary mode (only newlines are line terminators).

The charset may be forced at load time using the Charset pulldown menu. Choosing [Default] will cause the system default charset to be used if the file has not been opened in jGRASP before, otherwise the previously selected charset will be remembered.

The language may be forced at load time using the\ Language pulldown menu. This only applies to files that have not been previously opened in jGRASP. Once a file is opened, its language is remembered.

To conveniently open multiple files, click on the "pin" icon to keep the dialog up.

To change to the current directory of the jGRASP Browse window, click on the folder icon with the "B" in it.

---

Browse Window

This window, which is located on the Browse tab, acts as a file browser.

A combo box shows the current directory and has a list of file system roots. You can type a new directory in directly and hit "Enter" to change to that directory.

The Bookmarks menu displays bookmarks, and allows bookmarking the current directory and editing bookmarks.

Filters for the languages supported by jGRASP are provided, as well as the "all files" filter. Note that language filters classify files based on the extension only if they have not been opened in jGRASP before. Once a file is opened, jGRASP remembers that language. The default language for files with a ".h" extension can be set to C++ or C only (not both) by changing the extension settings for C or C++ (see settings).

You can also type a list of extensions into the filter pulldown and hit "Enter" to filter by extensions. These must be separated by whitespace, and can start with ".", "*.", or nothing. For example: "*.c *.cpp", ".c .cpp", and "c cpp" will all show only files that end in ".c" or ".cpp".

Clicking on a file will open it (in text mode). HTML files will be opened in the system default browser, and JAR files in the JAR/zip extractor. To edit one of these files, you can drag it onto a virtual desktop or use the context menu to open it.

Clicking on a project will attempt to open it. If it does not appear to be a jGRASP project, it will be opened as a file.

A context menu allows selected files to be opened (in text or binary mode), selected files to be deleted, selected files to be added to the active project with relative (to the project file location) paths only, or the properties of selected files to be displayed.

---

Project Window

This window, which is located on the Browse tab, displays files in the currently open projects.

Clicking on a file will open it (in text mode).

If the project contains Java files, a "UML" icon allows the UML diagram to be created or updated and shown.

A file context menu allows selected files to be opened or removed from the project, for relative paths to be made absolute or vice versa, and for source files to be changed to test files and vice versa.

A project context menu allows operations found in the active project menu to be performed on any project.

---

Message Window

The message window contains tabbed pages for compiler messages, messages from jGRASP (CSD generation, non-critical errors and warnings, etc.), an I/O window for run functions, and an interactions window which provides a Java statement and expression interpreter.

Color settings for these pages use CSD color settings. Some of these are specific to the message pages. They can be set on the CSD window settings CSD page.

Clicking on an error in a message window will open the file referred to in the message (if not already open) and select the line referred to in the message. Clicking on a line from a Java stack dump in the Run I/O window will do the same. If line numbers are frozen in the CSD window, the frozen line number will be selected. Clickable lines are shown in a different color. The format for click-to-error in the compile message page is determined by the compiler settings. For simple file names or Java class names (not full paths), open files and project or source file directories are searched. Additional paths that will be searched are specified on the sources page of the CSD window settings (workspace and project only).

The compile and jGRASP message pages have a Copy button. This will copy the selected text, or all text if there is no selection, to the clipboard.

The jGRASP messages page has a Stop button that will terminate any potentially time consuming internal process. This button is enabled only when such a process is active.

The compile page has a Stop button that will kill the compile process. This button is enabled only when a compile process is active.

The run page provides I/O for run functions. An End button allows the running process to be killed. This button is enabled only when a "run" process is active.

The interactions page provides a Java statement and expression interpreter, and echoes I/O for run functions. An End button allows the running process to be killed. This button is enabled only when a "run" process is active.

All four pages have a Clear button that clears previous output or I/O.

---

Projects

A jGRASP project consists of a file list, CSD and print settings (see settings), UML diagram state, tool result states (JUnit testing, etc.), and canvas window states. For now there are very few operations on non-Java projects; they mainly provide compiler environments through the CSD settings.

The project associated with the CSD window, CPG window, UML window, or canvas that is in focus will be active. When compiling or running, if a file belongs to more than one open project, the project settings for the most recently opened one will be used for the operation. The active project is displayed at the top of the control panel.

Any operation that will close a project will first save it. There is no way to discard changes to a project.

The project window displays the currently open projects and the files they contain.

The project menu allows various operations to be performed on the active project.

---

Multi-file Search Dialog

This dialog allows multiple files to be searched. The results are reported to the jGRASP Message window, in a clickable format. Row and column numbers in the results assume the file will be opened in text mode (as will happen if you click on a result and the file is not already open). If the file is opened in binary mode, the column number will be off by one for any line for which the previous line is terminated by "\r\n".

Filters for the languages supported by jGRASP are provided, as well as the "all files" filter. Note that language filters classify files based on the extension only if they have not been opened in jGRASP before. Once a file is opened, jGRASP remembers that language. The default language for files with a ".h" extension can be set to C++ or C only (not both) by changing the extension settings for C or C++ (see settings).

You can also type a list of extensions into the "Filter Extensions" field to filter by extensions. These must be separated by whitespace, and can start with ".", "*.", or nothing. For example: "*.c *.cpp", ".c .cpp", and "c cpp" will all show only files that end in ".c" or ".cpp". Note that you can do the same thing by entering filter expressions in the "File Name" field, such as "*.c" or "*.c|*.cpp" .

To change to the current directory of the jGRASP Browse window, click on the folder icon with the "B" in it.

Note that cancelling the dialog does not stop the search. To stop the search, you must hit the Stop button on the Compile Messages window.

Files and directories can be selected. For each directory selected, any files in that directory matching the selected filter will be searched.

Search Pattern - the text or pattern for which to search.

Pattern Type

Case Sensitive - if on, the search will be case sensitive.

Search Subdirectories - if on, subdirectories of any directories in the search will be recursively scanned. Any files matching the selected filter will be searched.

Search Project Files - if on, all files and directories in all open projects will be searched.

Max. Results Per File - specifies the maximum number of matches that will be reported for each selected file.

---

Generate Documentation Dialog

Target Directory - the directory in which the "javadoc" documentation will be generated. Using a project-relative path will allow this setting to be valid if the entire project is moved (even to a different operating system).

Include Private Items - if checked, private fields and methods will be included in the documentation.

Include Test Files - if checked, documentation will be generated for test files as well as source files.

Additional Doc. Command Flags - additional flags to the "javadoc" command. This is useful for linking to Java API docs on the local system or the web. For example:

Generate - generates documentation using the current project-level "Document" command for Java.

---

New Workspace Dialog

Workspace Name - the name for the workspace that will appear in the workspaces menu.

Copy Settings, Open Files, and Projects from Current Workspace - if checked, the new workspace will be equivalent to the current one.

Copy Settings from Current Workspace - if checked, the new workspace will have the same settings as the current one, but will have no open projects and no open windows on the desktop.

Create an Uninitialized Workspace - if checked, the new workspace will have default settings, no open projects and no open windows on the desktop.

Open the New Workspace - if checked, the new workspace will be opened after it is created. Otherwise, the new workspace will be created but the current one will remain active.

---

Workspaces Dialog

This dialog displays all of the named (non-default) workspaces and allows workspaces to be created, deleted, and reordered. On the left is the workspace list, displaying all of the named workspaces. The workspaces list allows reordering by drag-and-drop.

New - opens a new workspace dialog.

Remove - permanently deletes the selection in the workspace list.

Open - opens the selection in the workspace list.

Sort by Name - sorts the workspace list and the workspace menu alphabetically by name. You can also drag-and-drop in the workspace list to reorder it.

Complexity Profile Graph (CPG)

The Complexity Profile Graph, or CPG, is a statement-level complexity or comprehensibility metric. Each segment, which corresponds roughly to a program statement, is assigned a complexity that is a weighted sum of:

The CPG window Data Sets menu allows any combination of these values and the total complexity to be viewed.

Currently, the CPG is implemented only for Java and Ada.

---

CPG Window

The main section of this window shows the complexity values for the currently selected data sets. If the source is unedited, selecting segments in the CPG window will select the corresponding text in the source CSD window, and vice versa. The selection in the CPG window is shown as a yellow background. If the source is unedited, a black rectangle shows the segments that are currently visible in the CSD window.

Each data set value is scaled in the display, by the weight used in computing the total complexity, unless there is only one data set, in which case it is shown unscaled.

The individual complexity values of the segment under the mouse cursor are shown in the message bar. If the weight of a particular data set is not 1.0, the value and weight are displayed.

The scale button allows the graph to be scaled, from two-pixel wide bars to screen-width bars.

If Scroll Lock is on, the CPG window and the CSD window from which it was generated will scroll as one. This option is not available if the source has been edited.

A scrollbar at the bottom of the window allows the CPG to be scrolled if it does not fit in the window.

• File Menu
• View Menu
• Data Sets Menu
• For other menus, see Control Panel

---

File Menu

These are additional menu items available when a CPG window is active. For the base set of menu items, see control panel file menu.

Close - closes the CPG window.

Save Data As - allows CPG complexity values to be saved in a straightforward text format.

Disconnect From Source Window - dissociates the CPG window from the source CSD window. A second CPG window can then be generated from the same source.

Escape Virtual Desktop / Enter Virtual Desktop - takes the CPG window in and out of a virtual desktop.

Raise/Lower - in a virtual desktop, move the CPG window to the front if it is not on top. If it is on top, move it to the back. Outside a virtual desktop, move the CPG window to the back.

---

View Menu

These are additional menu items available when a CPG window is active. For the base set of menu items, see control panel view menu.

Vertical Orientation - if on, the segments axis is vertical, and the complexity horizontal.

Show Key - if on, a key that shows the color for each data set is shown (if there is more than one active data set).

Show Axis Labels - if on, the segment and complexity axes are labeled. If there is only one active data set, the complexity axis is labeled with the name of that data set, otherwise it is labeled with "complexity".

Show Number Labels - if on, segment and complexity axes have value labels. The labels are evenly spaced based on a minimum inter-label separation.

---

Data Sets Menu

This menu allows each data set to be turned off or on.

CSD Window

"CSD window" is the name given to source code editor windows in jGRASP. The CSD window supports dropping of text (drag and drop). The title bar displays the language, filename, and modified state (an asterisk * is displayed after the filename if it is modified). Note that CSD generation is considered a modification only if it adds new lines to the code (which will happen if multiple structures start on one line), because even though it may change the text it will not change the code structure. Removing the CSD is never considered an edit.

The CSD window may be split horizontally or vertically for a dual view of the text. This can be done by using The Split View submenu of the View menu, or by clicking the small button in the extra space below the vertical scroll bar. The split state of the window is remembered when a file is closed and reopened.

A tool bar is provided for commonly used functions. The default position of this bar is above the text or at the top of the control panel, depending on the toolbar mode, but it may be floated or moved to the bottom (or the sides, which is not very useful). The toolbar mode (single, multiple, none) can be changed using the View menu.

A message bar displays the insert/overstrike mode state, and the current cursor line and column, character code at the cursor, and topmost visible line. If the view is split, the topmost visible line of both views is displayed. The default position of this bar is below the text or at the bottom of the control panel, depending on the message bar mode, but it may be floated or moved to the top (or the sides, which is not very useful). The message bar mode (single, multiple, none) can be changed using the View menu.

When running on systems that have the concept of a system-wide selection (known as the PRIMARY selection on XWindows systems), CSD window selection is a part of this mechanism. On other configurations/systems, there is a jGRASP-wide selection. The F9 key will search for the current selection, and Shift-F9 will search backward for the current selection, in a CSD window. The Find key and Shift-Find will do the same thing (if your keyboard has a Find key).

• File Menu
• Edit Menu
• View Menu
• Build Menu
• For other menus, see Control Panel

• Mouse Button Actions
• Keyboard Actions
• Folding
• Marks
• Bookmarks
• Breakpoints
• CSD Context Hints
• Brace Matching

---

File Menu

These are additional menu items available when a CSD window is active. For the base set of menu items, see control panel file menu.

Clear (outside of desktop only) - closes the currently open file and clears the text.

Open - brings up an open file dialog. If inside the desktop, open will open a new window. If outside the desktop, the opened file will replace the current file.

Close - closes the CSD window.

Save - saves the current file. By default it is saved with the same line terminator format (binary, DOS, or Mac.) and charset as it had when loaded.

Save As - allows you to save the current file under a new name, and with a choice of line terminators (binary, DOS format, Mac. format) and charset.

Backup As - allows you to save a backup of the current file under a new name, and with a choice of line terminators (binary, DOS format, Mac. format).

Print

Generate UML Class Diagram (Java only) - pops up the UML diagram and updates the information for the current file. See UML window for information on jGRASP UML.

Generate Documentation - if the current compiler environment has a "document" command, runs that command and displays the documentation produced. Currently only the Java compiler environments have "document" commands.

Show Documentation - shows documentation generated with Generate Documentation, or generated at the project level.

Complexity Profile Graph - Click here for information about the CPG and CPG window.

Escape Virtual Desktop / Enter Virtual Desktop - moves this window to/from a virtual desktop to a free-floating frame.

Raise/Lower - in a virtual desktop, move the CSD window to the front if it is not on top. If it is on top, move it to the back. Outside a virtual desktop, move the CSD window to the back.

---

Edit Menu

These are additional menu items available when a CSD window is active. For the base set of menu items, see control panel edit menu.

Undo - this will undo the last edit. Folding is considered an edit in this context even though it does not modify the text, because folds must be undone to properly undo a sequence of edits. There is a limit to the total size of edits stored, but the last edit will always be stored no matter how large it is, and for multiple edits like a "replace all", they will all be stored.

Redo - redo an edit that was undone.

Cut - copies selected text to the clipboard then deletes it.

Copy - copies selected text to the clipboard.

Paste - paste text from the clipboard.

Paste Special - brings up a dialog that allows you to choose from the available formats for the current clipboard contents, and paste in that format.

Block Cut/Paste - turn block selection mode on or off. In block mode, cut, copy, paste, find, etc. work on rectangular blocks of text. If the end of a line is selected, the block will extend infinitely to the right (the ends of all lines in the block will be included). A cut will never delete lines, and a paste will not add lines unless the text is too short, in which case lines may be added to the end of the text.

Select All - selects all text in the window.

Find/Replace - brings up the find dialog.

Find Selection - search forward or backward for the current selection. The system-wide selection (sometimes called the PRIMARY selection) is used on systems that have that concept. Otherwise, the jGRASP-wide selection is used.

Goto Line - brings up a dialog that allows you to jump to a specific line.

Insert Template - A menu that allows predefined templates to be inserted into the text. These are inserted at the current cursor position, and indented to match the current cursor position. You may define templates in the template directory of the .grasp_settings directory in your home directory (typically C:\Users\user_name on Windows systems). For now, there is no easy way to do this. A template editor will be added later. The template format can be seen by examining the system templates in the "data" directory of the jGRASP distribution. The template files are named "templ.ext", where ext is an extension that indicates to which language the template applies.

Spaces/Tabs

Reserved Words (languages with case-insensitive reserved words only)

Comment - for languages that have single-line comments, comments each line of the selected text.

Uncomment - for languages that have single-line comments, removes the first such comment on each line of the selected text.

---

View Menu

These are additional menu items available when a CPG window is active. For the base set of menu items, see control panel view menu.

Generate CSD - generates a CSD.

Remove CSD - removes the CSD.

Fold - see folding.

Marks - see marks.

Bookmark - see bookmarks.

Breakpoints - see breakpoints.

Window Layout - allows you to select from a single view CSD window, or a vertically or horizontally split dual view.

Line Numbers - if on, line numbers are shown to the left of the text.

Freeze Numbers - when turned on, further edits will not change the line numbers. Also, click-to-error from a message window will use these frozen numbers. This is useful for finding multiple compile errors while editing the text.

Visible Toolbar Groups - allows groups of toolbar buttons to be hidden or shown.

---

Build Menu

This menu provides compile and run functions set up in the CSD window settings dialog. Output for compiling appears in the message window, which also provides a button to stop the compile process. Input and output for running are provided by the message window, which also contains a button to end the running process.

For Java projects, the Clean menu button will remove all class files corresponding to all source files in the project. This will not remove "old" class files (including old inner classes) for which the source no longer exists. For J2ME projects, all class files, temporary class files, and the project JAR and JAD files, will be removed.

The Debug Mode menu checkbox switches compiler debug mode on and off. This may change the compile commands, depending on the compiler environment that is being used. This is a global setting (applies to all CSD windows).

The Enable Assertions menu checkbox turns on assertions for Java compilation. This is a global setting (applies to all CSD windows).

The Run Arguments checkbox switches an arguments toolbar on and off. When on, arguments entered in the toolbar will REPLACE those in the settings.

If the Run in Windows Console checkbox (Windows only) is on, Run, Run as Applet, and Debug will use a DOS shell for I/O. You will be prompted in the DOS shell to hit a key to start the process and to continue after the process is finished. You can right click on the title bar and change the window properties, including width and height, before starting.

If the Mark I/O Streams as TTYs checkbox (Windows only) is on, stdin will be marked as a TTY using undocumented structures of the Windows C library, unless the target program is a Cygwin executable or is run in a DOS shell. For most executables, this will make the program behave as if it is being run from the command prompt. That is, it will prevent programs from buffering output. This may cause some executables (MinGW and Cygwin implementations of gdb, for example) to malfunction.

If the Non-canonical Input checkbox (non-Windows only) is on, input control characters such as EOF (04 or Ctrl-D) will be passed to the program instead of being processed, unless the target program turns canonical mode on for stdin. Note that in general, the "Close Input Stream" (Ctrl-Z) function of the Run I/O Window will not do anything when non-canonical input is turned on, except to send a 04 character to the target program and eliminate the possibility of future input. If you want to test binary input with a true EOF, you will have to run from outside jGRASP.

If the Run Topmost checkbox (Windows only) is on, then the application being run or debugged will be in an "always on top" mode. If your application needs to control the Z-order of windows, or if it launches other gui applications, then you may want to turn this off.

If the Focus to Run I/O Window When Running checkbox is on, keyboard focus will move to the Run I/O window when running.

The Project's Main File menu allows setting the main file for the project to the current file, or clearing the project's main file. This is used by all Java and some other compiler environments to determine which class or file is the target of a run or debug command.

Before a compile, if auto save is on, all modified files are saved (this setting is on the control panel Settings menu).

Before a compile, if auto save is off, any modified files are backed up and the current text is saved. The modification times for modified files are changed only if the file has been modified since the last compile, so files will not be unnecessarily recompiled. After the compile, the files are restored from backup. Because of this, while compiling with modified files, quitting jGRASP is not allowed and you should not kill jGRASP.

Java Workbench (Java files only)

---

Find Dialog / Page

This is the dialog or page for find and replace in CSD windows. All CSD windows in a virtual desktop share a common find page, the actions of which apply to the currently selected CSD window in the desktop. Each CSD window that is outside the desktop has its own find dialog.

Find - the search text. For regular expression token-based searches, token patterns are separated by hashes (#). Hashes in the patterns must be escaped by backslashes.

Replace With - the replacement text. For regular expression searches, the first capturing group matched will be replaced, or if there are no capturing groups the entire match will be replaced.

Case Sensitive - if off, the search will ignore case.

Match

Search

Folds

Find - searches forward in the text.

Find Backward - searches backward in the text.

Replace - replaces the current selection with the replacement text.

Replace All - replaces all occurrences of the search text with the replacement text. If the search or replace text contains a newline (spans multiple lines), or if regular expression mode is on, all folds will be removed.

Replace All in Selection - replaces all occurrences of the search text that occur entirely within the current selection with the replacement text. If the search or replace text contains a newline (spans multiple lines), all folds within the selection will be removed.

Replace Then Find - same as a Replace followed by a Find.

Find and Mark All - applies marks to all occurrences of the search text.

Clear All Marks - removes all marks.

---

Open File Dialog

A dialog for opening files.

Filters for the languages supported by jGRASP are provided, as well as the "all files" filter. Note that language filters classify files based on the extension only if they have not been opened in jGRASP before. Once a file is opened, jGRASP remembers that language. The default language for files with a ".h" extension can be set to C++ or C only (not both) by changing the extension settings for C or C++ (see settings).

You can also type a list of extensions into the Filter Extensions field to filter by extensions. These must be separated by whitespace, and can start with ".", "*.", or nothing. For example: "*.c *.cpp", ".c .cpp", and "c cpp" will all show only files that end in ".c" or ".cpp". Note that you can do the same thing by entering filter expressions in the File Name field, such as "*.c" or "*.c|*.cpp" .

The Text / Binary radio buttons allow the file to be opened in text mode (UNIX, DOS, and Mac. line terminators accepted) or binary mode (only newlines are line terminators).

The charset may be forced at load time using the Charset pulldown menu. Choosing [Default] will cause the system default charset to be used if the file has not been opened in jGRASP before, otherwise the previously selected charset will be remembered.

The language may be forced at load time using the Language pulldown menu. This only applies to files that have not been previously opened in jGRASP. Once a file is opened, its language is remembered.

To change to the current directory of the jGRASP Browse window, click on the folder icon with the "B" in it.

---

Mouse Button Actions

Left Mouse Button

Middle Mouse Button - Extends the current selection.

Right Mouse Button - if CSD Window popup is enabled, brings up the popup menu, otherwise:

---

Keyboard Actions

These are keyboard actions that are not shortcuts for menu items and are not completely standard for text or source code editors.

Ctrl/Cmd + [ - if cursor is on a parenthesis, curly bracket, or square brace, moves it to the matching item.

Ctrl/Cmd + Left Arrow or Right Arrow - moves the cursor left or right to the next language token boundary or the start or end of the line if the token extends across multiple lines. If the cursor is within a comment or string or the language is plain text, moves the cursor left or right to the next whitespace-delimited word boundary.

Ctrl/Cmd + Backspace - deletes text on the left of the cursor to the nearest language token boundary or the start of the line if the token extends across multiple lines. If the cursor is within a comment or string or the language is plain text, deletes to the next whitespace-delimited word boundary to the left of the cursor.

Ctrl/Cmd + Delete - deletes text on the right of the cursor to the nearest language token boundary or the end of the line if the token extends across multiple lines. If the cursor is within a comment or string or the language is plain text, deletes to the next whitespace-delimited word boundary to the right of the cursor.

Ctrl/Cmd + Up Arrow or Down Arrow - moves the cursor up or down to the next blank-line-delimited paragraph boundary.

Home - moves the cursor to the start of the line.

End - moves the cursor to the end of the line.

Ctrl/Cmd + Home - moves the cursor to the start of the text.

Ctrl/Cmd + End - moves the cursor to the end of the text.

---

Folding

The jGRASP CSD window allows text folding based on CSD structure, and arbitrary folding. This folding is line-based: two or more lines are folded into one. For CSD structures, the first line remains unfolded. The second line (first folded line) displays the CSD folding symbol (a box with a plus inside) and if the second line contained only a comment, that comment. The fold commands are available on the View > Fold menu, through accelerator keys, and through mouse actions on the CSD. If the menu or accelerator key is used, folding is applied to the current text cursor position. For mouse clicking, it is applied to the position clicked on.

When text is edited after a CSD is generated, the foldable structure is maintained as much as possible. An edited CSD may fold in unexpected ways - regenerating the CSD will fix this.

The CSD structure containing the cursor is considered to be the innermost structure if the cursor is in the text, or the nearest CSD stem if the cursor is in the CSD. Note that each statement and declaration is a structure, even if it is on a single line. Activating a fold command with the cursor on the text of such a line will not fold the enclosing structure.

Fold operations are a part of the stream of edits, and can be undone using Ctrl-Z or the Undo item of the Edit menu. Unfold All however, can not be undone.

The fold operations are:

---

Marks

The CSD window supports multiple highlights called marks. Marks are separate from the selected text. They are used only for display, not for cut and copy. These highlights are transitory: they will not survive CSD generation or be saved when a file is closed.

A menu is provided on the CSD window View menu that allows the current selection to be marked, all marks to be removed, and the text to be searched for the next or previous mark. The find dialog also has a "find all" function that uses marks.

---

Bookmarks

The CSD window provides line-oriented bookmarks. These are displayed to the left of the text, as green trapezoids. They are persistent, and will be saved and restored when a file is closed and reopened.

A menu is provided on the CSD window View menu that allows the bookmark on the line containing the cursor to be toggled on or off, all bookmarks to be removed, and the text to be searched for the next or previous bookmark.

A left mouse click in the left border of a CSD window with the Alt key down will toggle a bookmark.

---

Breakpoints

Breakpoints are used in the integrated Java debugger. These are displayed to the left of the text, as red octagons. They are persistent, and will be saved and restored when a file is closed and reopened. If you are not using the integrated Java debugger, you can use breakpoints as additional bookmarks.

For a breakpoint on a non-code line, the Java debugger will stop at the next valid line. While the debugger or workbench is running, such a breakpoint will be shown with an "X" through it.

A menu is provided on the CSD window View menu that allows the breakpoint on the line containing the cursor to be toggled on or off, all breakpoints to be removed, and the text to be searched for the next or previous breakpoint.

A left mouse click in the left border of a CSD window will toggle a breakpoint.

---

CSD Context Hints

With this feature turned on and a CSD generated, the top or bottom of any structure that is off-screen can be viewed by moving the mouse over the structure stem. If the structure is one where defining information is at the top (anything except a test-at-the-bottom loop), the top line of that structure will be shown at the top of the CSD window. For loops with a test at the bottom (do-while), the bottom line of the structure will be shown at the bottom of the CSD window. Holding down the "Ctrl" key will reverse this (show the top of a do-while or the bottom of any other structure).

For nested or multi-stage structures, such as nested if/else or switch/case, the top or bottom line of the innermost structure or stage (last "else if" or case, for example) is normally shown. Hold down the "Shift" key to see the top or bottom line of the entire structure.

CSD context hints can be turned off on the Control Panel Settings menu.

---

Brace Matching

Moving the mouse over a brace, bracket, or parenthesis will highlight that character and the matching brace, bracket, or parenthesis. This can be turned off using Settings > CSD Window Settings > Workspace. When it is off, holding down the ctrl key will enable brace matching.

---

GNU Extensions to C and C++

Most of the GNU C and C++ extensions are supported for CSD generation. Additional extensions are supported if the Allow GNU Extensions box is checked in the compiler settings.

Function attributes for C are not supported unless Allow GNU Extensions is checked because the syntax is too close to that of a K&R style function definition. You can get around this by defining __attribute__ to nothing in the predefined macros.

Nested functions are not supported. These can not be distinguished from declarations without identifier context. Our C parser does not distinguish variables from type names, so that header parsing can be avoided.

Breaking strings across lines without using backslashes will not be supported. CSD generation adds text at the beginning of lines, so the original string might not be recovered if there were a syntax error that caused the start of the string to not be recognized. The backslash at the end of a line applies regardless of syntactic context, so there is no danger of corrupting backslash-continued strings during CSD generation.

Integrated Java Debugger

jGRASP has an integrated debugger for Java. When the debug command is run, if it responds with a transport address (a line like "Listening for transport X at address: Y." ), jGRASP will start the debugger. The default "jdk (integrated debugger, HotSpot VM) - generic" compiler environment will debug an application or applet with most 1.3 or higher JDKs.

To use the integrated debugger, jGRASP must be running under the JDK (not a JRE). If you are having some problem with this (you get a "tools.jar file not on classpath" message when attempting to debug), putting the JDK bin directory at the beginning of the PATH should fix this. For a detailed description of how the jGRASP startup programs find/choose java, see Running jGRASP.

Using the integrated debugger may lock up jGRASP occasionally with older jdks. If this happens consistently (every time or every time for some particular target program), or if there are stack dumps from jGRASP, let us know.

---

Debug Window and Workbench

• Toolbar
• Threads Window
• Call Stack Window
• Variables Window
• Eval Window
• Workbench
• Display of Values
• Operations on Values
• Breakpoints
• Watches

---

Toolbar

Open Canvas - opens a new canvas file, or if a program is being debugged and there are canvas files related to the running project or file, brings up a dialog that allows one of those canvases or a new canvas to be opened.

Step Over - steps the selected thread within the current method or code block. The thread must be suspended to step. In normal step mode, this will execute approximately one line of source code in the current method. If "byte code size steps" is selected, approximately one byte code instruction will be executed. While the thread is stepping, "(stepping)" is displayed in its description in the threads window. Multiple threads can be stepped at the same time. Hitting Suspend will kill the step. When the step is completed, if the stepping thread or no thread is selected, the current source line will be selected; if another thread is selected, no action will be taken.

Step In - like step over, but will enter any method calls.

Step Out - like step over, but will step out of the current method or code block.

Step to Cursor - runs to the cursor for the active CSD window within the virtual desktop(s). All breakpoints are ignored during this operation, but watchpoints are not.

Suspend - suspends the selected thread, or all threads within the selected group.

Resume - starts the selected thread, or all threads within the selected group.

Auto Step - when on, stepping will automatically repeat, for an animation effect. A delay window controls the time spent in the stopped state after each step.

Auto Resume - when on, resuming will automatically repeat (the program will resume after any breakpoint or watchpoint is hit), for an animation effect. A delay window controls the time spent in the stopped state at each breakpoint or watchpoint.

Byte Code Steps - when on, use the smallest step size possible. Otherwise, the step size is approximately one source line.

Suspend New Threads - if on, any new threads that start will immediately be suspended. If on when the debugging process is started, all startup threads are suspended as soon as is possible.

---

Threads Window

Shows the state of each thread, organized within the thread group tree. Suspended threads are shown in red, running threads in green. This window is updated dynamically, so you can see the state of running threads change. The thread description is as follows:

name [state] (debugger action/state) monitors

For a simple, non-gui application, there will be a "main" thread, any threads that your code creates, and several system support threads (Signal Dispatcher, Reference Handler, Finalizer). For applets or gui applications, there will be numerous event queue, gui, and system threads.

---

Call Stack Window

Shows the current call stack for the selected thread, if the thread is suspended. When the thread is resumed, this window is disabled. Each frame of the stack shows the method, filename, line number if available, and program counter. The program counter is the current byte code index within the method. Selecting a frame will select the source line, if the corresponding source file can be found, and show the associated variables in the variables window. A source file can be located if the class is in a file that is in an open CSD window or is in the current project; or if the file package root is the working directory for the debug operation (which it commonly is), or is one of the Sources entries of the active project.

---

Variables Window

Shows the available variables for the current frame of the call stack. The target code must be compiled in debug mode, or not much information will be available here.

this or static - shows fields for the current object if within an instance method or instance initializer, or static fields available within the current static context.

Arguments - shows arguments to the current method if within a method.

Locals - shows the current local variables.

Values are displayed as described in Display of Values

---

Eval Window

Shows the value, in the current debugger context, of limited Java expressions that you enter. These expressions are a subclass of Java expressions with the following limitations:

If classes used in these expressions have not been loaded, they will not be forced to load, and this may result in a "cannot resolve symbol" or similar error. This is in contrast to workbench and workbench-like operations (invoke method, create instance) which will force-load any classes used.

The package java.lang is available (for classes that have been loaded), but the imports for the source file of the current debugger context (if the source file is available) are not. So to access java.awt.Color.red, for example, you must use the full package/class name (and the class "java.awt.Color" must have been loaded in the target VM).

Values are displayed as described in Display of Values. Operations can be performed on values using a context menu. These are described in Operations on Values.

---

Workbench

A place to put objects so that they can be conveniently monitored or operated on. Objects on the workbench will not be garbage collected until they are removed from the workbench. The workbench can also be used without a debugged program, by creating instances and invoking methods directly from the UML diagram or from a CSD window.

Values are displayed as described in Display of Values. Operations can be performed on values using a context menu. These are described in Operations on Values.

---

Display of Values

Values are displayed in a tree, where the field values of each Object or the elements of each array are its children in the tree.

Operations can be performed on values using a context menu. These are described in Operations on Values.

Ctrl-C or dragging will copy a string representation of the value if it is a primitive or String, otherwise it will copy the name of the item in the current scope, including any necessary casting.

For Object values, a unique id is displayed. Any Objects with the same id are the same Object.

The declared type of objects is shown. The runtime type is shown in parenthesis along with the unique id. For elements with generic declared type, the generic type parameter name is shown, along with the replacement type if available and the bounds otherwise. Note that there is no such thing as "generic runtime type", since generics are purely a compile-time mechanism in Java. This can lead to some confusing cases, such as a field of type "String" (declared with a generic parameter) containing, for example, an Integer. Such things can be accomplished in code through casting the parent object to a type without generic parameters, and are currently allowed without warning through jGRASP debugger and workbench operations.

Note that another thread may change values while you are viewing them. To update the displayed values when debugging a multi-threaded program, collapse then expand the parent node.

Objects are shown as squares, primitive types as triangles. All non-fields are colored blue. Field icons are color coded based on the declared type of the object containing them (the actual type may be a subclass or interface implementation). The color coding indicates the relationship between the declaring type of the field and the declared type of the object as follows:

Static fields are shown underlined.

For arrays, at most ten elements are shown at once. To change the elements that are shown, select the object then click on it (but don't double click). A slider bar will appear, on which you can select the first element shown. To jump directly to an element, use "Goto Array Element" on the context menu.

Any non-visible fields are shown with a gray bar over the icon. This includes masked fields, as well as fields with yellow and white icons as described above. Basically, fields displayed with a gray bar are not visible from the declared type of the enclosing object unless it is casted.

Fields that are inaccessible in the context of the selected call stack frame are shown with a red bar over the icon. If these fields are also non-visible, the bar will be half red and half gray.

Watches: Fields can be watched for access or modification if the target JVM supports it. To create a watchpoint, select a field and then right click. A popup menu will allow you to set a modification or access watchpoint, or to remove them if they are set. A Watch All will set a watchpoint on all fields with the same signature as the selected field (including those in subclasses and superclasses of the field's object type). A simple Watch will set a watchpoint only for the selected field's object. Fields that are being watched for modification are shown with a black triangle pointing up in the center of the icon, those with an access watch are shown with the triangle pointing down, while those with both will have a black square. Setting a lot of watches can slow down debugging.

---

Operations on Values

Depending on context and type of value, any of the following operations may be available (these will be described in more detail in a future release):

Select Viewable Array Elements - for an opened array with more than ten elements, makes the index selection slider visible.

Goto Array Element - for an opened array with more than ten elements, allows the first visible index to be selected.

Watch for Modification - for fields, causes the debugger to stop when the field is next modified.

Watch for Access - for fields, causes the debugger to stop when the field is next accessed.

Watch All for Modification - for fields, causes the debugger to stop when a field with this signature is next modified.

Watch All for Access - for fields, causes the debugger to stop when a field with this signature is next accessed.

Add to Workbench - for non-null Objects, puts the Object on the workbench.

Invoke Method - invokes an instance or static method on an Object, or a static method on the type of the value if not a non-null Object.

Create New Instance - creates a new instance of the class of the value.

Create Array Of - creates an array of the type of the value.

Change Value - for fields, changes the value of the field.

View by Name - brings up a viewer showing the value for the name of the selected item. For example, if you view a String named "str" in the current scope, and it is assigned to a new String, you will see the new string. When "str" goes out-of-scope, you will no longer see the value.

View Value - brings up a viewer for the value. If the value is an object, it will be tracked indefinitely, and will be protected from garbage collection while it is being viewed.

Copy Name - copies the name of the selected item, with any necessary casts, to the clipboard. You could use this name in the current scope to access the object, assuming it is accessible.

Copy Value - for primitive objects and Strings, copies a string representation of the value to the clipboard.

Create New Instance of Named Class - allows a new instance of an arbitrary class type to be created.

Create Array of Named Class - allows an array of an arbitrary type value.

Invoke Static Method on Named Class - allows a static method to be invoked on an arbitrary class type.

---

Breakpoints

Breakpoints can be set in the CSD windows using the View > Breakpoints menu, the context menu, or by moving the mouse over the "breakpoint zone" at the left of a CSD window (the mouse cursor will change to a breakpoint) and left-clicking. Only breakpoints in open CSD windows are active (when a CSD window is closed, the breakpoints will go away, when one is opened, the breakpoints will become active). Breakpoints can be added or removed while the debugger is running.

While the debugger is running, invalid breakpoints (breakpoints set on lines that do not contain executable code) are shown crossed out, and the debugger will stop at the next valid line. If the class files for a particular source file can not be found, the breakpoints are shown with a slash through them. In order for this mechanism to work, the source file and associated class files must be located in the same directory, or the code must be running in a jGRASP project with appropriate source and class directories set.

Fixed Bugs and New Features

In the following we use "crash" to mean an uncaught exception which triggers a "crash report" dialog in jGRASP. This may or may not be a real problem - many uncaught exceptions do not cause any harm.

---

New Features in Version 2.0.6_05

Support for text blocks added.

Support for yield statement added.

---

Bugs in Version 2.0.6_03 Fixed in Version 2.0.6_04

Focus follows mouse is on by default, though the setting shows that it is off.

Generating a CSD with the cursor near the end of text, undoing the generate, then redoing it may cause a crash if the CSD added lines.

Generating a CSD for a file containing only spaces then performing an "undo" will cause a crash.

---

Bugs in Version 2.0.6_02 Fixed in Version 2.0.6_03

If a UML window is put into the virtual desktop, attempting to close the associated project and possibly other operations will cause a crash.

---

Bugs in Version 2.0.6_01 Fixed in Version 2.0.6_02

Use of array index selection slider in debug variables tree causes a crash.

Using arrow keys to select theme in welcome dialog causes a crash.

Error dialogs when selecing theme in welcome dialog may be hidden beneath welcome dialog.

---

Bugs in Version 2.0.6 Fixed in Version 2.0.6_01

CSD generation for C/C++/Objective-C fails for code that contains /* */ comments.

jGRASP fails to launch if it is intalled at a file sytem root directory.

jGRASP startup settings launch from Mac control shell fails.

Out-of-range port number in WebCAT assignment definition URL causes a crash instead of error message.

---

Bugs in Version 2.0.6 Beta Fixed in Version 2.0.6 Beta 2

Automatic color adjustment for text colors will only flatten them if necessary, and not brighten them when needed.

---

Bugs in Version 2.0.5_07 Fixed in Version 2.0.5_08

Interactions does not force class loading for method return types. Attempts to invoke methods on unloaded methods may fail with an incorrect error message, or may invoke a method with the same signature in the current context if one exists.

---

New Features in Version 2.0.5_08

Modified and added Checkstyle checks files to account for changes in Checkstyle 8.20 and 8.21.

---

New Features in Version 2.0.5_07

Support added for AdoptOpenJDK, Corretto, Zulu, Red Hat, Liberica, and SapMachine OpenJDK distributions.

---

Bugs in Version 2.0.5_05 Fixed in Version 2.0.5_06

Illegal characters with code > 255 in C or C++ preprocessing expressions may cause a crash during CSD generation or syntax coloring (code display).

---

Bugs in Version 2.0.5_04 Fixed in Version 2.0.5_05

If a Java file ends in a backslash or a backslash followed by a series of 'u' characters and has a length that is a multiple of a certain number, various operations will cause a crash.

Java API help link for Java version 11 is not correct.

Interactions results that end in \r or \r\n will be displayed with an unclosed bracket in the margin.

---

Bugs in Version 2.0.5_03 Fixed in Version 2.0.5_04

For JUnit and other tools, auto-compile of a file or project will be considered a failure if there are clickable lines in the output, even if these are warnings rather than errors.

Try-with-resources with externally declared resource (introduced in Java 9) is not supported for CSD, CPG, interactions.

Switch statement blocks with multiple case labels are executed multiple times in interactions.

For-each statements with primitive array initializers do not work in interactions. With object initializers of the wrong type they may fail with incorrect error messages.

---

Bugs in Version 2.0.5_01 Fixed in Version 2.0.5_02

jGRASP help does not work if Microsoft Edge is the default browser.

Native startup and wedge executables built on Linux may not be used.

Help and documentation links may go to top of page rather than anchor on some macOS and Linux systems.

C/C++ compile commands should have two flag locations (FLAGS and FLAGS2 in the compiler settings), as some compilers are picky about flag locations.

Selecting an element of the array elements viewer if it is in a subview will cause a crash.

---

Bugs in Version 2.0.5_01 Fixed in Version 2.0.5_02

jGRASP help does not work if Microsoft Edge is the default browser.

Native startup and wedge executables built on Linux may not be used.

How To

---

How To Set Up JavaFX for Java 11 and Higher

As of Java 11, JavaFX is no longer included in the Java distribution. JavaFX is available at https://openjfx.io. Download and extract the appropriate JavaFX SDK for your OS. Make sure the version of JavaFX you are using matches or is compatible with the Java version you are using. If you are running on a recent version of MacOS, use the latest versions of JavaFX and Java. Older versions may not work.

Next, go to Settings > Compiler Settings > Workspace (you can also do this at the project or file level if you will use different versions of JavaFX for different projects or files). Select language Java if not already selected. Select the JavaFX tab. Click off the default box for JavaFX Home and set the contents to the root directory of the extracted JavaFX installation.

Normally you will only use the javafx_controls module, but if other modules will be used they can be set in JavaFX Modules as a comma-separated list.

---

How To Create a New File

On the control panel menu, go to File > New File and select the desired language. Languages that have not been used recently can be found under Other.

You can also select File > Open File, go to the desired directory, and type in a file name that does not exist. jGRASP will then ask if it should be created. You can force the selection of language using the Language combo box. If this is set to Default, the language will be selected based on the file extension.

If jGRASP is on your system's PATH, from the command line you can go to the desired directory and type "jgrasp some_file". If some_file does not exist, jGRASP will ask if it should be created. The language will be selected based on the file extension.

To change the language for a file once it is created, see the next item.

---

How To Change the Language of a File

To change the language of a file, select Edit > Compiler Settings > File on the CSD window menu. Choose the Compiler tab on the settings dialog. Select the desired language from the Language combo box. Once a language is selected, jGRASP will remember this setting. Also, the icons in file dialogs and in the browse window will reflect this setting.

---

How To Open a File

The File > Recent Files menu on the control panel is an easy way to open recently used files.

Another convenient way to open a file is to use the browse window. You can double click on a file to open it in text mode. If the file is HTML and you want to edit it rather than opening it in the documentation viewer, you can drag it from the file browser to a virtual desktop. This will also open it in text mode. If you need to open the file in binary mode (show and edit all line terminator characters other than newlines, treat the file as unencoded bytes), right click on the file and select Edit Binary. All of these methods will choose a language based on the file extension if the file has not previously been opened in jGRASP, otherwise it will choose the last language used for the file.

On most systems, you can drag files from file browsers or other applications onto the jGRASP desktop and they will open in text mode.

If jGRASP is on your system's PATH, from the command line you can go to the desired directory and type "jgrasp some_file". This will open some_file in text mode.

From the control panel menu, File > Open File will bring up an open file dialog. This will allow you to open files in text or binary mode and with a specified or default language and charset.

If the file is in an open project, you can double click on the file in the project window or if a UML window is open, double click on the class (or one of the classes) in the diagram.

---

How To Save a File

Hit Ctrl-S or File > Save in the CSD window. If the file is unnamed, you will be prompted for a name.

Hit Ctrl+Shift-S or File > Backup As to save a backup of the file without changing the file you are editing.

Hitting File > Save As in the CSD window will bring up a Save As dialog. This dialog allows you to change the line terminator type and charset.

---

How To Compile a Program

For languages such as Java with run-time linking, Build > Compile will compile the file or project, and in the case of a single Java file, out-of-date dependencies (note that dependencies are compiled, not dependents). For languages such as C++ with build-time linking, Build > Compile and Link will create the executable for a single-file program or project, while Compile will compile the file only. For most jGRASP compiler environments, Build > Make will call the "make" command in the directory containing the file. This allows you to create a more elaborate build process than that provided by Compile and Link.

For Java projects, if a UML window is open, Build > Compile All from the UML window will compile the project.

---

How To Run a Program / Pass Command Line Arguments

Typically, Build > Run from the CSD window will run the program. For some languages, such as Java, you can specify a main file for a project using Build > Workspace's Main File. After that, you can use Build > Run from any file in the project, not just the "main" file.

To pass command line arguments, click Build > Run Arguments. A toolbar will appear in which you can specify the arguments.

To set command line arguments for the whole project, go to Edit > Compiler Settings > Project (the file must be in a project), select the Flags / Args / Main tab, click off the default box for FLAGS or ARGS and Run, and enter the arguments. Note that the Run Arguments toolbar will override this setting. The FLAGS2 or ARGS2 flags are used in some languages, such as Java, to send arguments to the runtime system rather than the program itself. In Java for example, you could set FLAGS2 or ARGS2 X Run to -Xmx2000m to set the maximum size of the memory allocation pool to 2000MB.

---

How To Run a Program in a DOS Window

On Windows, click Build > Run in Windows Console. After that, programs will run in a DOS window. Currently, Java programs can not be debugged (using the jGRASP debugger) with I/O from/to a DOS window, but this will be implemented in the future.

---

How To Create a New Project

From the control panel menu, Project > New will bring up a "new project" dialog. From there you choose the project filename and other properties. If Add Files to Project Now is checked on the last page of the dialog, an "add files" dialog will pop up after you create the project. If the project is to be a Java project and Open UML Window is checked, a new UML diagram will be created for the project.

---

How To Add Files to a Project

Files can be added with either relative or absolute paths. Files in the project that "belong to the project" should be added with relative paths, so that the project file and member files can all be moved or copied. If some file is at a fixed position on the system, add it to the project with an absolute path so that it can still be found when the rest of the project is moved or copied.

The simplest way to add files to a project is to drag them from the browse window to the project window. The project into which the file(s) will be dropped is highlighted as you drag over the project window. The files will be added with relative paths. On most systems, files can also be dragged from an external file browser or other application to the jGRASP project window.

Selecting Add Files from the project window context menu for the desired project will bring up an "add files" dialog.

For the active project, selecting Project > Add Files on the control panel menu will bring up an "add files" dialog. You can also add files to a project using Add to Project on the browse window context menu.

If a UML window is open for the project, you can drag files into it from the browse window, or on most systems, from an external file browser or other application.

---

How To Remove Files from a Project

In the project window, select all the files you want removed (from one or more projects) and either bring up the context menu and select "Remove From Project(s)" or select Project > Remove Selected Files From Project(s) from the control panel menu.

Selecting Project > Close on the control panel menu will allow you to close any open project.

---

How To Open an Existing Project

The Project > Recent Projects menu is an easy way to open recently used projects.

Double clicking on the project in the browse window will open it.

Project > Open Project from the control panel menu will bring up a dialog that allows you to select and open a project.

---

How To Close a Project

Select Close from the project window context menu for the project you want to close.

To close any open project, select Project > Close on the control panel menu.

---

How To Search for Selected Text

F9 and Shift-F9 or Find and Shift-Find will search forward and backward for the selected text in a CSD window or message window. This works across CSD windows and message windows - the selected text does not have to be in the window being searched.

---

How To Link Project Documentation to Java API Documentation

In the Additional Doc. Command Flags box of the documentation dialog, enter "-link" followed by the URL of the Java API. For example:

local file: -link "file:///C:/Program Files/Java/jdk-10.0.1/docs/api"
Oracle website: -link "https://docs.oracle.com/javase/10/docs/api"

The Java API documentation can be downloaded from http://www.oracle.com/technetwork/java/index.html.

---

How To Make ".h" a Default File Extension for C or C++ Files Only

Default extensions can be set for each workspace. Select Settings > Compiler Settings > Workspace on from the control panel or a CSD window. Select "C" or "C++" from the Language combo box, whichever one you don't want to be the default. Select the Extensions tab, click the default box for extensions off, and add the desired extensions (without "h" or "H"). You can use Ctrl-C and Ctrl-V to copy the old extensions and paste them back after clicking the default box off.

---

How To Generate a CSD for C or C++ Files With Lots of Ugly Macros

If you set up the CSD generation environment (include path, predefined macros) exactly like the environment your compile command sees, and set the Include Files mode to All Files, and if no structures are partly in a header file and partly in a source file (like an included function header), and if the code is ANSI C, CSD generation should work for your code. Setting all that up can be a pain, and parsing thousands of lines of headers can be slow, so this is usually not an option, unless you just want to generate a CSD once for printing or viewing.

If you can edit the code, the easiest thing to do is surround weird code with #ifndef _GRASP_IGNORE and #endif . _GRASP_IGNORE is set in the predefined macros for all compiler environments by default. For example:

This is an MFC message map. Without the ifndef, if all headers are parsed and the include path is set correctly, a CSD will be generated for this structure, but the indentation will not be what you expect, because the real structure is not what you expect.

For compiler extensions, setting predefined macros in the compiler environment can solve many problems. For example, you might define far to be nothing in an old 16 bit compiler.

For your own code, it is a good idea to use macros that look like real code. For example, you should leave a trailing semicolon out of a macro so it will be required in the code.

---

How To Change the Classpath for Java Programs

Go to Settings > PATH/CLASSPATH > Workspace from the control panel.

Select the CLASSPATH tab in the settings dialog if not already selected, then hit the New button.

In the New CLASSPATH / Doc Path dialog, click the Browse button for Path or JAR File and navigate to the JAR file or the folder containing the target Java package root, and click Choose.

(Optional) If you would like set the documentation path for the classes in the JAR or package folder, click the Browse button for Documentation Path, select the folder containing the associated javadoc documentation, and click Choose.

Finally, click OK on the New CLASSPATH / Doc Path dialog, and OK on the settings dialog.

Interactions

The interactions window allows Java expressions and statements to be entered and evaluated. The entered code can reference classes and variables in a program that is being debugged and items on the workbench. It can be used in the context of a debug session, workbench session, or alone (an interactions session).

• Using Interactions
• Added Language Features
• Bugs, Missing Features, Future Features

---

Using Interactions

Starting - To use interactions, enter a Java expression, statement, or multiple statements in the interactions window and hit "Enter". If a debug or workbench session is underway, you can reference debugger variables and/or workbench items in the interactions input. If no such session is underway, an "interactions session" will be started. All I/O in the Run I/O Window is echoed to the interactions window and vice versa.

Entering Code - The lines of code that are entered will be evaluated as soon as a syntactically complete statement or expression is reached. Thus, "x = 3" will be evaluated immediately, while "x = 3 +" will be prepended to the following line. The bracket to the left of the input remains open while more input is expected, and becomes closed once it is complete. This bracket can also be double-clicked to fold up multi-line output. To enter a line and prevent it from being evaluated, hold down the "Shift" key while hitting "Enter".

Results - For expressions, the result of the expression evaluation is displayed below the expression. This result is the "toString()" value for objects and an appropriate string representation for primitives. For multi-line results, a bracket is shown to the left and double-clicking on it will fold up the result. For statements, no output is shown. Thus, if an int named "x" is in scope, "x = 3" will produce the result "3", while "x = 3;" will produce no result. Bare declarations (without a trailing semicolon), such as "long l" or "int x = 3" can also be entered and will be evaluated without producing a result.

Program Input - When input is requested on standard input, a box appears in the Interactions Window. While the program is waiting on input, the normal interactions functionality is blocked. For now, there is no way to turn this off, so if a program has a thread that is continuously reading from stdin, it will not be possible to use interactions.

Accessibility - When the debugger is stopped, the access context for interactions is the same as that of the selected debugger stack frame (the current position of the debugger by default). When in "workbench mode" or "interactions mode", the access context is "some unknown class in some unknown package". In other words, only access to public fields and methods is allowed. The "access checking" toolbar button on the interactions window allows access checking to be turned off. With access checking off, all Java entities become accessible. According to the JLS, turning off access checking in this way should not change the results of name resolution, but due to difference in the way the javac compiler (and our interactions window, which follows javac where it differs from the spec) actually resolves names, in some cases where there are nested classes and fields with identical names in a class, different meanings for identical qualified names are possible.

Debugger Local Variables - Variables in a debug session are not available to the debugger before assignment. This is due to the nature of Java bytecode, and there is no meaningful way for us to work around it. There is also no way to tell if a local variable or method argument in the debug target process was declared final, so reassignment to final local variables and method arguments in the debugger through interactions expressions and statements is allowed. Assignment to final fields in the debug target from interactions is not allowed.

Scope and Name Resolution - The outer scope of interactions is the jGRASP workbench. Thus, evaluating "int x = 3;" will add an int variable named "x" to the workbench. Variables can not be declared if their names are already used for workbench items. Inner scopes of interactions do not correspond to the workbench, so "{int x = 3;}" will not add an item to the workbench. The interactions scope takes precedence over debugger scope(s). So if a variable named "x" is declared in interactions and a local variable named "x" exists at the current debugger location, "x" will refer to the interactions variable. You can access a local variable or argument "x" in this case using `local`x . For a field named "x", you can qualify it using this.x .

---

Added Language Features

The interpreted nature of interactions and ability to interact with the jGRASP debugger and workbench make desirable certain language features that are not available or needed in standard Java.

Unimport - Import declarations can be undone by adding a minus sign after the "import" keyword. For example, "import java.util.List" can be undone by "import - java.util.List" and "import java.util.*" undone by "import - java.util.*".

Undeclare - Interactions variables can be "undeclared" by removing them from the workbench using the workbench context (right-click) menu. A language feature may be added in the future to allow this to be done directly from interactions.

---

Bugs, Missing Features, Future Features

Interactions is under development. The following paragraphs describe known bugs, missing features, and features that will be added in the future. Planned "language features" are described above.

Static Import - static import declarations are not yet implemented.

Uninitialized Variables - all variables declared in interactions are initialized with default values, as though they were fields. In the future, they will be uninitialized and the JLS rules of definite assignment will be applied to entered code so that access on a potentially uninitialized variable will result in an error. Final variables will also be allowed and potential reassignment of final variables will result in an error.

Debugger Echo - for operations performed through the "invoke method" and "change value" dialogs in the jGRASP debugger and workbench, equivalent text expressions will be echoed to the interactions window.

Method Declarations - future versions will allow static methods to be declared and used in interactions.

Generics - Java generics are not yet supported. Support for generics within interactions will be added in the future. In spite of type erasure, most generic parameter information is available for fields and variables in the debugger, but there may be some limitations and inconsistencies when referencing program variables.

JAR/Zip Creation Dialog

This dialog allows you to create a zip archive or executable jar file for the current project.

• First Page
• Second Page

---

First Page

Archive Type - selects either a jar or zip format. You must use the jar format to create an executable jar file, and should use the zip format for archiving.

Project Files - selects the type of files from the current project to include in the jar or zip file. The files are shown in the window below.

Additional (non-project) Files - the Add button allows you to add arbitrary files to the jar or zip file. Using a relative path (the default) means that the correct files will be used if the entire project is moved to another directory. The Delete button will delete selected files from the window.

JAR File or Zip File - the name of the JAR or zip file to be created. Uses a project-relative path by default.

Create Zip (zip files only) - creates the zip file.

---

Second Page (JAR files only)

Main Class - the name of the main class in the JAR file. If specified, running "java -jar" on (or possibly clicking on) the generated JAR file will run that class. The combo-box gives a choice of classes with entry (main) methods.

Manifest Entries - lists the entries that will be included in the JAR manifest and allows you to add additional entries. Entering text on the last, blank line will create a new entry.

Create JAR - creates the JAR file.

---

JAR/Zip Extractor Dialog

This dialog allows you to extract files from a JAR or zip archive. Once an archive is opened, all files or selected files can be extracted to a directory using Extract Files. Files can also be dragged from the window and dropped elsewhere.

Installing jGRASP

Important Notes

This is jGRASP version 2.0.6_09. Check https://www.jgrasp.org for the latest version of jGRASP.

jGRASP is written in Java. Java 1.6 (JDK 6) or higher must be installed on your machine in order to run jGRASP. The full JDK 1.5 or higher (not just the JRE) is required in order to use the integrated Java debugger and workbench.

jGRASP does not include any compilers. In order to compile programs you must have a compiler installed.

Which JVM to Use

The latest Oracle JDK is suggested. If you are using a very new version of Java or a non-Oracle version, you may get a startup message telling you that jGRASP has known problems or minor problems, or has not been tested on your system.

Installing from the Self-Extracting exe on Windows

Before running the installation file, you should close all applications. If a file from a previous installation is in use, the installer may give you a "Can not copy file" or "File in use" message. This would happen, for example, if you had the readme.txt file open in MS Word. If this happens, iconify the installer, close the file or the application that is using the file, pop the installer back up, and click Retry on the error dialog. If the installer will not run, you will have to install manually.

On Windows, if you have Administrator access, the start menu items and desktop shortcut will be installed for all users.

For a silent install, use the /Q flag. This will install in the standard location with a desktop shortcut and start menu items, but no new file associations. You can use "/D=install_directory" to specify an alternate install location. Note that there will be no test to ensure that jGRASP is not running when this flag is used. If jGRASP is running while it is upgraded, it is likely to crash.

Manual Installation on Windows

Unzip the distribution file in the directory where you wish to install jGRASP. This will create a jgrasp directory containing all the files. On 64 bit systems, add a shortcut or start menu item to jgrasp\bin\jgrasp64.exe; on 32 bit systems, add a shortcut or start menu item to jgrasp\bin\jgrasp.exe.

Installing on macOS

Double click on the .pkg file if it did not run automatically after downloading. A root password is required to install.

Manual installation on macOS

Unzip the distribution file in the directory where you wish to install jGRASP. This will create a jgrasp directory containing all the files. You can then click on "jgrasp/bin/osx/jcs" to run jGRASP.

If you want to create a "normal" macOS application, copy the "jgrasp/bin/osx/jcs.app" directory to the target location, then move the original "jgrasp" directory (the whole thing) into the copied "jcs.app/Contents/Resources" directory. If you don't want two versions of jGRASP to show up on the macOS Start With menu, delete the "jgrasp/bin/osx/jcs.app/Contents/Resources/jgrasp/bin/osx" directory.

Installing on Linux

Unzip the distribution file in the directory where you wish to install jGRASP. This will create a jgrasp directory containing all the files. You may need to set executable permissions on all files, using chmod -R 777 jgrasp (777 is read/write/execute permissions for all - change as appropriate). You may want to add the "bin" subdirectory to your execution path or create a soft link to .../jgrasp/bin/jgrasp from a directory on the executable path.

The bin/create_linux_launcher.sh script will create a desktop launcher for jGRASP on most Linux systems.

Note that java must be on your system path in order to run jGRASP.

The first time you compile or run a program jGRASP will attempt to build the native "wedge" and startup shell programs. This may fail due to file permission issues or for other reasons, in which case jGRASP will use a less capable pure Java wedge. Without the native wedge, when you run a Java program I/O will usually be line buffered, and when you run a C or C++ program I/O will usually be block buffered (which is useless for interactive command line I/O). To build the native parts from the command line, cd to the jGRASP "src" directory. Run ./configure and if successful run ./Make.sh .

Please contact us if building the native "wedge" fails for some reason other than a C compiler not being installed.

Installing on Other Systems

Unzip the distribution file in the directory where you wish to install jGRASP. This will create a jgrasp directory containing all the files. You may need to set executable permissions on all files. On UNIX-based systems, you would do this using chmod -R 777 jgrasp (777 is read/write/execute permissions for all - change as appropriate). On Linux or UNIX based systems, you may want to add the "bin" subdirectory to your execution path or create a soft link to .../jgrasp/bin/jgrasp from a directory on the executable path.

The first time you compile or run a program jGRASP will attempt to build the native "wedge" and startup shell programs. This will fail if your system is not Linux or UNIX based. It may also fail due to file permission issues or for other reasons. If it does fail, jGRASP will use a less capable pure Java wedge. Without the native wedge, when you run a Java program I/O will usually be line buffered, and when you run a C or C++ program I/O will usually be block buffered (which is useless for interactive command line I/O). To build the native parts from the command line on Linux and UNIX based systems, cd to the jGRASP "src" directory. Run ./configure and if successful run ./Make.sh .

Please contact us if your system is Linux or UNIX based and building the native "wedge" fails for some reason other than a C compiler not being installed.

If you are on a system other than Windows or a Linux or UNIX variant and have a good knowledge of system programming on your system, you may be able to build a wedge based on the UNIX wedge sources found in jgrasp/src . The executable must be jgrasp/internal_bin/sys_run .

Network Administration

jGRASP supports common settings for all users on a network. The common settings directory can be specified at installation time if using the self-extracting exe on Windows. Otherwise, in the "data" directory of the installation, create a file called "admin". Specify the directory to be used for administrator settings in this file. This should be the only contents of the file, and not be followed by a line feed or carriage return. Use a full path to specify the directory. This directory must be accessible and readable by all users, and writable only for administrators. You should select a location outside the jGRASP distribution, so that you can continue to use the settings after upgrading.

When an administrator (anyone with write access in the common settings directory) runs jGRASP, menu items that allow you to change administrator settings will appear on the control panel settings menu. Also, when copying or creating compiler environments, you will have the choice of creating them for all users or just the current user.

---

Linux Multi-click Interval Fix

Due to Oracle bug 5076635, the multi-click interval time on many Linux systems is set to 200ms regardless of the desktop setting. This means that you have to double-click very fast or it will register as two single clicks. This bug affects all Java applications. The following paragraphs describe a procedure that will usually solve this problem.

Look for a file in your home directory named .Xdefaults or .Xresources. If one of those exists, open it up in jGRASP; otherwise, open a new file using File > New > Plain Text.

Add the following line to the file:

Half a second (500ms) is a reasonable multi-click interval for most people, but you can use a different value if you like.

Save the file. If it is a new file, save it in your home directory as ".Xdefaults".

Shut down jGRASP and log out or run the following at the command line:

(or .Xresources if that is the file you edited).

Log back in and/or restart jGRASP. If the problem is not fixed after creating a new .Xdefaults file, try again using .Xresources.

---

Running jGRASP

jGRASP requires a Java 1.6 (JDK 6) or better virtual machine and system classes to run. You can get the latest JDK from Oracle.

Running on Windows

The bin\jgrasp.exe file will start jGRASP in single-instance mode. Running jGRASP a second time will pop up the currently running instance. If you chose to associate file extensions with jGRASP during installation, clicking on an associated file will pop up the file in the currently running instance. A Windows application titled "jGRASP Control Shell" is available from the Windows system tray. This displays the jGRASP output (including stack dumps if there is a crash) and allows you to kill jGRASP if it locks up. It will first try a "soft kill", and if jGRASP does not exit within a few seconds, a "hard kill" will be issued.

"bin\jgrasp.exe" or "bin\jgrasp64.exe" will search for a java.exe to run jGRASP in the following manner:

The method used to find java.exe and the java command used to start jGRASP will be displayed in the jGRASP Control Shell window.

If jGRASP will not run normally, please report the problem. As a last resort, you should be able to run the "jgrasp.jar" file manually from the command prompt. Some minor features, such as deleted files being moved to the Windows recycle bin, will be missing. If "java.exe" is not on your system PATH, you'll need the full path to Java. For example, with jGRASP installed in the default location, you would do:

Running on macOS

Double clicking on the "jGRASP" app file, or on "jgrasp/bin/osx/jcs.app" if jGRASP was manually installed, will start jGRASP in single-instance mode. Running jGRASP a second time will pop up the currently running instance. Clicking on an associated file will pop up the file in the currently running instance. An application titled "jGRASP Control Shell", which initially runs minimized, displays the jGRASP output (including stack dumps if there is a crash) and the command used to start jGRASP, and allows you to kill jGRASP if it locks up. It will first try a "soft kill", and if jGRASP does not exit within a few seconds, a "hard kill" will be issued.

jGRASP will select Apple Java 6 over Oracle Java 7 if both 6 and 7 are present and Java 8 or higher is not. Oracle Java 7 tends to have slow display performance and poor support for retina (uneven font sizes, etc.) compared to Apple Java 6. This is much improved on newer versions of Oracle Java 8.

If jGRASP will not run normally, please report the problem. As a last resort, you should be able to run the "jgrasp.jar" file manually from a terminal window. Some minor features, such as opening files by double clicking in Finder, will be missing. For example, with jGRASP installed in the default location, you would do:

Running on Linux and Other UNIX Systems

Similar single-instance mode executables exist for x86 Linux. These can be accessed through the bin/jgrasp shell script, which will also pass the location of the jGRASP installation to the correct executable so you don't have to. A window titled "jGRASP exec", which initially runs minimized, allows you to kill jGRASP if it locks up. It will first try a "soft kill", and if jGRASP does not exit within a few seconds, a "hard kill" will be issued.

On other UNIX systems, bin/jgrasp should run jGRASP directly, without a single-instance shell. See Installing on Other Systems for information on compiling the native parts of jGRASP.

For the "java" startup script, if the location of java is not specified through a "-a" command line parameter or JGRASP_JAVA environment variable, then "java" must be on the path.

Requirements for the Integrated Debugger

For both the Windows and UNIX/Linux startup programs, to use the integrated Java debugger, "java.exe" or "java" must be in the JDK directory structure (in /bin, where tools.jar is in /lib), unless the "-cp" command line argument or JGRASP_CLASSPATH environment variable is used.

On Apple Java, the integrated debugger will be available by default.

Command Line Arguments for the Single Instance Executables and Shells

A filename can be given as the last argument. The leading dash for flags can also be a forward slash on Windows.

---

Installing and Running jGRASP in Portable Mode

jGRASP can be run in portable mode from a USB drive or other portable drive. In this mode, all opened files and projects, project files, etc. are stored in a drive-relative and OS-neutral format, so that the jGRASP desktop, projects, etc. can be used regardless of the Windows drive letter or Linux/Unix/Mac mount directory for the drive, and regardless of the OS on which the drive is installed. jGRASP startup settings will also be stored on the portable drive. The Java installation used to run jGRASP may be on the portable drive or on the local system(s).

Installing Portable jGRASP

To install jGRASP for portable use, download the .zip installation file and unzip anywhere on a portable drive. Settings will be stored in a ".grasp_settings" directory in the same directory that contains the jGRASP root directory "jgrasp". Startup settings will be stored in a "jGRASP_ss" file also in that same directory. These settings will not be lost when upgrading.

If desired, Java may be installed on the portable drive by copying files from a Java installation on the desired OS. Settings > jGRASP Startup Settings (while running in portable mode) can be used to select that Java executable for use by jGRASP (by default it will run under the current system's "java"), or on Windows by running bin\winconfig_portable.bat before running jGRASP.

Running in Portable Mode

The bin\jgrasp_portable.bat file will start jGRASP in portable mode on 64 bit Windows systems, while bin\jgrasp_portable32.bat must be used on 32 bit Windows systems. On other operating systems, jGRASP can be started in portable mode by running "jgrasp -p drive_root" from the "jgrasp/bin" directory, where drive_root is the current mount point for the portable drive.

---

Command Line Arguments for jGRASP Itself.

---

Using Help

The frame on the left side can be one of:

• Contents - links to major subjects.
• Index - alphabetized list of links to subject headings.
• Search (jGRASP only) - a search of the help text.

At the top of each of these pages is a link to the other two. Clicking on any other links will change the page in the frame on the right side.

The search page searches for sections containing all words entered in the Search field.

---

Control Structure Diagram (CSD)

The Control Structure Diagram, or CSD, is an algorithmic level diagram intended to improve the comprehensibility of source code by clearly depicting control constructs, control paths, and the overall structure of each program unit. The CSD is an alternative to flow charts and other graphical representations of algorithms. The major goal behind its creation was that it be an intuitive and compact graphical notation that was easy to use manually and relatively straightforward to automate.

A primary purpose of jGRASP is to provide for automatic generation of the CSD for source code written in Java, C, C++, Objective-C, Ada, VHDL, and Python.

---

Interface Terminology

These terms are used throughout this documentation.

---

Known Bugs

Check the known bugs list at https://www.jgrasp.org for an updated list of known bugs, if you are not already there. Check the future plans page for a list of future features. Here is the bug-fix history.

---

Our Known Bugs

Output in interactions is not shown until all processing is complete. Input in interactions will appear above the interactions text that caused it to be requested, and will not be correctly ordered with output. This will be fixed in the next release.

Interactions is not Java 8 compatible.

Interactions is missing some Java language features: static import, uninitialized variables (interactions locals are now initialized as if they were fields), generics.

Interactions does not allow the minimum long and integer constants to be used.

In the Java debugger and workbench, if a field exists in an implemented interface of the declared type of an object, and a field with the same name exists in the superclass but is "not inherited" according to JLS terminology (is declared private or is inaccessible from the child), the field declared in the interface will be shown as "not visible" (it will have a red bar through it), although it should be visible (jGRASP definition of "visible" is "available without casting"). This is due to Oracle bug 6655791, but we may work around it in a future jGRASP release.

In the Java debugger and workbench, elements with replaced generic type are displayed with the replaced type (when known), but for "invoke method" and other operations, they are treated as the actual run-time type. Also, generic type parameters supplied when creating an instance are not thoroughly checked for validity, and arguments for "invoke method" or "create instance" are not checked for compile-time validity with respect to generic replacements or generic type parameter bounds. These problems don't limit the use of the debugger or workbench in any way, and they will be fixed in a future release.

---

Bugs Caused by Java, Swing, or Window Manager Problems

These are difficult or impossible to work around. The eventual "fix" for them is (or will be) to get a newer version of the JDK. Many of them apply only to old versions of the JDK.

File chooser details view does not resize rows when the font size is changed under some JDKs (all file choosers).

Performance is bad and there is much unnecessary repainting with the Mac Look-And-Feel and Nimbus Look-And-Feel.

On some UNIX/Linux VMs, running jGRASP through the single-instance shell will cause the JVM to crash at shutdown. This seems to be harmless.

Memory leaks - due to Swing bugs, there are some small memory leaks. These have been minimized as much as was possible. This should not be a problem unless you run jGRASP for weeks without restarting. There may be larger memory leaks that we are unaware of.

---

Future Features / Missing Features

Check the future plans page at https://www.jgrasp.org for an updated list of planned future features, if you are not already there.

Current Development

Future

---

Reporting Bugs / Requesting Features

If you are having a problem with a compile or run command, make sure the command works from the DOS command prompt or UNIX/Linux command line before contacting us.

If you are having a problem with a compile or run command, clear the Compile Messages or Run I/O window, turn on Verbose Messages under the Settings menu, execute the compile or run command, and copy and send us all of the output. This will make it much easier for us to determine the nature of the problem.

Check the known bugs or future plans page at https://www.jgrasp.org before reporting a bug or requesting a feature.

The preferred way to send a bug report or request a feature is using the Report a Bug menu under Help. Using this will send us system information (OS, Java version, etc.) that may be essential in helping us to track down the bug or understand your request.

You can also email bug reports and feature requests to graspATengDOTauburnDOTedu. Be sure to include the version number, and for bug reports, the system you are using and the stack dump if any.

---

About jGRASP

jGRASP version 2.0.6_09.

Built on January 31, 2022.

Copyright 1999-2022 Auburn University

Website:

Project Director:

Chief Software Engineer:

Empirical Evaluation:

Cyber Research:

---

Acknowledgements:

The development of jGRASP has been supported by a research grant from the National Science Foundation.

The development of previous versions of GRASP was supported by research grants from NASA Marshall Space Flight Center, the Department of Defense Advanced Research Projects Agency (ARPA), and the Defense Information Systems Agency (DISA).

Free code used in jGRASP (thanks to all who provided it):

---

jGRASP^TM License

Software License for jGRASP Version 2.0.6_09

Copyright 1999-2022 Auburn University

Section 1. License Grant.

Auburn University grants to you a non-exclusive and non-transferable license to use jGRASP and the associated documentation provided in jgrasp/help, collectively "jGRASP". jGRASP may be installed for use on one or more computers or on a local area network. The "wedge" source code provided in the jgrasp/src directory is free of license restrictions. It may be used or modified for any purpose. The plugin source code provided in the jgrasp/extensions directory, with the exception of the Web-CAT tool plugin sources, may be used or modified for any purpose, but when linked with the jGRASP jar file, the results may only be used as jGRASP plugins. See the Web-CAT source files for license information specific to that plugin. Source code for our slightly modified version of the Eclipse Web-CAT submission plugin is available upon request. jGRASP is a Trademark of Auburn University.

Section 2. Restrictions

Distribution of jGRASP is not permitted without written permission (see Supplements), except that it may be distributed internally within a single organization. Distribution of components of jGRASP separately from the whole is not permitted, except that the complete associated documentation provided in jgrasp/help may be distributed separately. Reverse engineering of jGRASP is not permitted. Any use of image files, icons, or executable components of jGRASP separately from the whole is prohibited.

Section 3. Disclaimer of Warranty

jGRASP is licensed "as is". There are no express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Auburn University makes no warranty with respect to the accuracy or completeness of information obtained through the use of this program. Auburn University does not warrant that jGRASP will meet all of your requirements or that its operation will be uninterrupted or error free or that any defect within jGRASP will be corrected. No oral or written information, representation, or advice given by Auburn University or an authorized representative of Auburn University shall create a warranty. Auburn University and its agents shall in no event be held liable to the user for any damages, including direct, indirect, incidental, or consequential damages, lost profits, lost savings, or other such damages arising out of the installation, use, improper use, or inability to use jGRASP, even if Auburn University has been advised of the possibility of such damages, or any claim by any other person or entity related thereto.

Section 4. Third Party Software

Bundled Software:

Software that is bundled with jGRASP, if present, is not subject to this license. This software will be within a directory named "bundled" in the jGRASP installation. All such software is independently usable. Check the individual project websites for license details. Bundled software may include:

Product	License	Website
Oracle OpenJDK	GPLv2	https://openjdk.java.net
Checkstyle	LGPL-2.1+	https://checkstyle.org
JUnit 4	EPLv1.0	https://junit.org/junit4

File putbi8a.pfb, Utopia Font (used under the TeX Users Group sublicense):

Copyright 1989, 1991 Adobe Systems Incorporated. All rights reserved.

Utopia(R)

Utopia is either a registered trademark or trademark of Adobe Systems Incorporated in the United States and/or other countries. Used under license.

ADOBE MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE SOFTWARE FOR ANY PURPOSE. IT IS PROVIDED "AS-IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. ADOBE DISCLAIMS ALL WARRANTIES WITH REGARD TO THE SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL ADOBE BE LIABLE TO YOU OR ANY OTHER PARTY FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER WHETHER IN AN ACTION OF CONTRACT NEGLIGENCE, STRICT LIABILITY OR ANY OTHER ACTION ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ADOBE WILL NOT PROVIDE ANY TRAINING OR OTHER SUPPORT FOR THE SOFTWARE.

See file "utopia_license.txt" in the "data" directory for the full license.

File OpenSans-Semibold.ttf, Open Sans Font:

Digitized data copyright © 2010-2011, Google Corporation.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Supplements

Distribution for Educational Purposes - Publishers may distribute the jGRASP software and the jGRASP Handbook (Tutorials and Reference) on media that accompany their textbooks provided that (1) the title "jGRASP(TM) 2.0.6_09 copyright 1999-2022 Auburn University" is included on each CD label, (2) descriptions of the CD indicate that jGRASP is included on the CD, and (3) a list of the textbooks that include jGRASP is provided to Auburn University (crossATengDOTauburnDOTedu). Permission to distribute jGRASP for educational purposes covers all media finalized prior to January 31, 2023 for inclusion in textbooks. While it is anticipated that distribution of jGRASP for educational purposes will remain royalty free, this supplement of the jGRASP license will be re-evaluated on an annual basis.

For additional information, contact James H. Cross II, Computer Science and Software Engineering, 3101 Shelby Center, Auburn University, AL 36849-5347 (334-844-6315, crossATengDOTauburnDOTedu).

Structure Identifier Viewers

The structure identifier viewers display the internal structure of linked data structures such as linked lists, binary trees, and hashtables, as well as array or list wrappers for structures such as stacks and queues. A structure identifier component in jGRASP will attempt to automatically determine the structure type for any object for which a viewer is launched. There are also built-in viewers for known classes such as java.util.LinkedList, which are faster and can handle a larger number of elements, but have less functionality (animation, displaying local variable nodes, showing bad links).

For linked structures, correct links are colored black, while incorrect ones are red. Links from local variable nodes to the structure or from field labels to the structure are colored green.

---

Structure Identifier View Configuration

The structure identifier view configuration allows you to specify or change the mapping between a class and a structure identifier viewer. When a class is viewed using the structure identifier viewer for the first time, the class is analyzed to determine potential mappings between the class and a linked list or binary tree view. Each of these is ranked with a confidence level. If at least one candidate is found, the viewer will use the mapping with the highest confidence level initially. These mappings only consider linked objects where class fields form the links. For other types of links (stored in an array, stored in a map, etc.) you will have to configure the mapping.

• Structure Page
• Fields Display Page
• Linked List Example
• Int Array Binary Tree Example

Structure Page

This page allows the structure type and class-to-view mapping to be edited.

Structure - allows you to choose one of the structure mappings that were found by the automatic structure identification system. Structures are listed in order of confidence. This may be empty if no mappings were found. Choosing one of the mappings will select a structure type, link mapping expressions, and other settings for the mapping. Those expressions and settings can then be modified if necessary.

Structure Type - manually selects the structure type.

Expressions - these expressions specify the way that the structure classes are mapped to the structure display.

• Linked List Expressions
• Binary Tree Expressions
• Hashtable Expressions
• Array Wrapper

For linked lists, the variable _list_ can be used in these expression to refer to the list itself, and for binary trees, _tree_ can be used to refer to the tree. Note that for local variable node display, these values will be null (except that the root node or head node expression will not be used for local variables). If the mapping is such that the list or tree reference itself is necessary to follow links, it should be obtained from the node reference if possible. Otherwise, the null case for _list_ or _tree_ should be handled by specifying expressions that evaluate to null in this situation.

The root node or head node expression specifies the first node in the tree or list. This should be left blank in cases where "the node is the structure". Unless this is a simple field reference (or blank), local variable nodes will not be displayed. In the future, a "Node Class" entry will be added to rectify this problem. If there is no actual node class (consider a linked list or binary tree encoded in an int array), a "simulated node" may be returned. This will be provided as the "node" in the other expressions. See the int array example in this section for an application of this method.

For other expressions, the variable _node_ refers to the current node. The expressions specify how to reach neighboring nodes from a node, and what value to display in a node.

Non-expression settings for the mapping may also be present.

Linked List Structure Expressions

Head Node Expression - expression for the head node. Typically this would be something like "_list_.head". It could be "_list_" if the linked list has no wrapper (the list "is" the head node).

Next Node Expression - expression for the next node from a node. Typically this would be something like "_node_.next". It could be something more complicated, such as a table lookup.

Previous Node Expression - expression for the previous node from a node in a doubly linked list, or blank for a singly linked list. Typically this would be something like "_node_.prev". It could be something more complicated, such as a table lookup.

Value Expressions - expressions for the values to be displayed. Multiple values are separated by hash signs (#). Typically this would be something like "_node_.value" or "_node_.key#_node_.value".

Node Text Expressions - expressions for the text of the values to be displayed, if different from the toString() value. For example, if the value itself is an integer index into an array, this could be "_list_.values[_value_]".

Node Class - class name for list nodes. If present, local variables of this type will be displayed and animated as they enter or leave the linked list. This may be set to "<Auto>", in which case the structure identifier will attempt to automatically determine the correct type. For some linked lists, such as an array-encoded list, there is no "node class" as such, and this should be left blank or set to "<Auto>".

Last Node Links to First - if on, a "next" link from the last node to the first will be considered correct, otherwise it will be considered incorrect.

First Node Links to Last - if on, a "previous" link from the first node to the last will be considered correct, otherwise it will be considered incorrect.

Node Index Labels - the format in which node labels should be displayed.

Binary Tree Structure Expressions

Root Node Expression - expression for the root node. Typically this would be something like "_tree_.root". It could be "_tree_" if the tree has no wrapper (the tree "is" the root node).

Left Node Expression - expression for the left child node from a node. Typically this would be something like "_node_.left". It could be something more complicated, such as a table lookup.

Right Node Expression - expression for the right child node from a node. Typically this would be something like "_node_.right". It could be something more complicated, such as a table lookup.

Value Expressions - expressions for the values to be displyed. Multiple values are separated by hash signs (#). Typically this would be something like "_node_.value" or "_node_.key#_node_.value".

Node Text Expressions - expressions for the text of the values to be displyed, if different from the toString() value. For example, if the value itself is an integer index into an array, this could be "_tree_.values[_value_]".

Dummy Node Expression - expression for a dummy or sink node for the tree. If present, this node will be shown without values and at the bottom of the tree.

Node Color Expression - determines the node color, if present. For example, in a red-black tree this could be "_node_.isBlack?0x666666:0xff6666"

Node Class - class name for tree nodes. If present, local variables of this type will be displayed and animated as they enter or leave the tree. This may be set to "<Auto>", in which case the structure identifier will attempt to automatically determine the correct type. For some binary trees, such as an array-encoded tree, there is no "node class" as such, and this should be left blank or set to "<Auto>".

Array Size Expression - if an array is to be displayed alongside the binary tree, this specifies the array size. For example, in a binary heap this could be "_tree_.heap.length". The "array" doesn't have to be an actual array, it could be a list structure, but it will be displayed as an array.

Array Element Expression - if an array is to be displayed alongside the binary tree, this specifies the array node to be displayed at each index. This expression will take the place of _node_ in the value expression when determining the value. For example, in a binary heap where the node type is "int", this could simply be "_index_"

Array Field Name - a field name for the array, for display purposes only.

Hashtable Structure Expressions

Element Count Expression - expression for the number of root elements. Typically this would be something like "(_table_.table == null)? 0 : _table_.table.length" (note the null test to handle an uninitialized table).

Element Expression - expression for each root element. Typically this would be something like "_table_.table[_index_]".

First Node Expression - expression for the first node in the chain at each root position. If the element expression provides the first node, this should be left blank. Otherwise, it would typically be something like "_element_.list".

Next Node Expression - expression for the next node in a chain. This would typically be something like "_node_.next".

Value Expressions - expressions for the values to be displyed. Multiple values are separated by hash signs (#). Typically this would be something like "_node_.key#_node_.value".

Node Text Expressions - expressions for the text of the values to be displyed, if different from the toString() value. For example, if the value itself is an integer index into an array, this could be "_table_.values[_value_]".

Node Class - class name for table nodes. If present, local variables of this type will be displayed and animated as they enter or leave the hashtable. This may be set to "<Auto>", in which case the structure identifier will attempt to automatically determine the correct type.

Array Wrapper Structure Expressions

Element Count Expression - expression for the number of elements. For a stack, this might be something like "(_struct_.data == null)? 0 : _struct_.data.length" (note the null test to handle an uninitialized stack).

Element Used Expression - if present, determines for each element if it is used or not. Unused values are shown with a lighter background. For a stack, this might be something like "_index_ < _struct_.top".

Element Expression - expression for each element. For a stack, this might be something like "_struct_.data[_index_]".

Index Expressions - expression for indexes to be displayed with the structure. For example, in a queue you might want to display "_struct_.head#_struct_.tail" (note that these would be displayed as "head" and "tail", with the "_struct_" prefix automatically omitted). Each index will be shown as an arrowhead pointing to the corresponding array element.

Fields Display Page

This page allows the selection of fields to display in the viewer. These will display the "toString()" value of the field, or an arrow to the value if the value is a node and appears in one of the displayed structures.

Linked List Example

Consider a singly linked list class, where "head" points to the first node, and in a node, "next" points to the next node while "value" holds the value of interest. The first node holds a real value and the "next" link for the last node is null.

Head Node Expression: _list_.head

Next Node Expression: _node_.next

Previous Node Expression: <left blank>

Value Expression: _node_.value

Last Node Links to First, First Node Links to Last, First Node is Dummy: all checked off

Int Array Binary Tree Example

Consider an int array used to hold a binary tree. Sets of three ints specify a node. The first is the index of the left child, the seconds is the index of the right child, and the third holds the value. A -1 index is used to represent null links. So new int[] { 3, 6, 0, -1, -1, 1, -1, -1, 9 } would be a tree containing three nodes, with "0" at the root, "1" as the left child, and "9" as the right child. In this case, there is no node class, so we will use an Integer as a stand-in node class, to hold the node index. The root expression just returns an Integer with value 0, or null if the array is empty. The left and right expressions return the Integer index of the left or right link, where _node_ is an Integer holding the index of the current link, or null if the index of the left or right link is -1.

Root Node Expression: (_tree_.length > 0)?Integer.valueOf(0):null

Left Node Expression: (_tree_[_node_.intValue()] >= 0)?Integer.valueOf(_tree_[_node_.intValue()]):null

Right Node Expression: (_tree_[_node_.intValue() + 1] >= 0)?Integer.valueOf(_tree_[_node_.intValue() + 1]):null

Value Expression: _tree_[_node_.intValue() + 2]

Note that we used "Integer.valueOf()" instead of "new Integer()". Because "Integer.valueOf()" caches results, there is a good chance that most or all of the animation will be displayed. The viewer animation relies on nodes being the same object (equal by ==). For "new Integer()", this would never be the case. Obviously a node ".equals()" comparison would make more sense here. This may be added as an option in the future. In any case, this will not affect the correct display of the structure, just whether or not all "moved" nodes will be shown in the process of moving.

Settings

• General Info
• CSD Window Settings Dialog
• Print Settings Dialog

---

General Info for Settings

There are three levels of CSD window and print settings in jGRASP: workspace, project, and file. Workspace settings apply to all files. Project settings apply to files in a particular project. File settings apply to a specific file. Each workspace setting can be overridden by a project setting, and each project setting by a file setting. In order to change the setting at any level (override the setting at the next level down), the default box (black square in a box) must be checked off. If it is not checked off, the current default setting is displayed, and is not editable. Note that this default setting is not a fixed value, but the value of the corresponding setting at the next level up (which can be changed), or for workspace settings, the system default value (which could change with a new release of jGRASP - but won't unless absolutely necessary).

If administrator settings are enabled, there wil be a fourth level of settings above workspace settings. This is convenient for computer lab administration, etc. See network administration.

In most cases, you will want personalized settings to apply to all CSD windows, in which case you should edit the workspace settings. If you use a variety of compiling environments for different projects, you would most likely edit compiler settings at the project level. Since the settings of the current project apply to all files, a single file can be used in different projects without conflict. File level settings would most commonly be used to override the default language for the file, and to add any file-specific compiler flags. Some settings, such as the CSD colors and font, can only be set at the workspace level.

---

CSD Window Settings Dialog

This dialog is used to set most properties not related to printing. The Colors, Font, and Charset pages are available only for workspace settings.

• OK Button - apply the settings and close the dialog.
• Apply Button - apply the settings without closing the dialog.
• Reset Button - reset the dialog to the currently active settings.
• Cancel Button - close the dialog without saving the settings.
• Compiler Page
• CSD Page
• Colors Page
• Font Page
• Sources Page
• PATH Page
• Charset Page

---

Compiler Page

Language specific settings page on the CSD window settings dialog.

• Language Combo Box
• Environment Page
• Flags/Args/Main Page
• Applet HTML Page
• JavaFX Page
• Extensions Page
• Variables

Language Combo Box

The Language combo box specifies the language for which settings are being viewed or edited, and for file level settings, the language of that file.

Environment page

"Compiler Environments" specify the compile and run commands (Make, Compile, Compile and Link, Semantic Check, Run, Debug, and for Java, Run Applet and Debug Applet), working directories, error formats, and environment variables.

System compiler environments, supplied with jGRASP, can be viewed or copied, but not edited or removed. The Java system compiler environments will attempt to use the same version of Java that jGRASP is running under to compile and run programs.

Local compiler environments, created by the administrator, can be edited or removed only by an administrator. These have names beginning with "local:".

User compiler environments, created by you, can be edited or removed. These have names beginning with "user:".

To use a compiler environment, select it in the list, then hit the Use button on the environment page (to the right of the list). The selected environment will become active once you hit Apply or OK on the settings dialog.

Use - uses the selected environment (not immediately applied).

New - creates a new environment using a compiler environment dialog.

Copy - copies the selected environment using a compiler environment dialog. It must be saved under a new name.

View - for system environments, displays the environment using a compiler environment dialog.

Edit - for user-created environments, allows the selected environment to be edited using a compiler environment dialog.

Remove - removes a user-created environment.

Flags/Args or Flags/Args/Main Page

Main File (project level only) - specifies the file used to substitute command variables beginning with MAIN_ or main_ . This is intended to be the file containing the executable module for languages such as Java or Ada. If no main file is used, "main" variables will be substituted with the current file (useful for single file projects). The %<PROJECT_PATH> and %<SEP> (or %/ or %\) variables can be used in the path.

FLAGS or ARGS - for each command, this will replace any %<FLAGS> or %<ARGS> variables. This is intended to be used for passing flags to a compiler or arguments to an executable.

FLAGS2 or ARGS2 - for each command, this will replace any <FLAGS2> or <ARGS2> variables. This can be used when multiple sets of flags are needed. In the Java compiler environments supplied with jGRASP, these are the arguments sent to the jvm during a "run", while FLAGS or ARGS are the arguments sent to the application.

Applet HTML Page

This specifies the contents of the temporary HTML file used for Run as Applet in Java. %<PATH>, %<FILE>, %<BASE>, %<file>, %<base>, %<PACKAGE>, and %<PACKAGE_PATH> variables may be used here.

JavaFX Page

This specifies the settings for JavaFX on Java 11 and higher (no setup is needed for earlier Java versions). Normally, only JavaFX Home needs to be set, to the root of the JavaFX installation. If you are using modules other than javafx_controls, these can be set in JavaFX Home as a comma-separated list.

Extensions Page (workspace level only)

Allows the default extensions for each language to be set. For a file that has not been opened in jGRASP before, these extensions determine which icon will be shown in the file browser page or in a file dialog, and which language will first be used when the file is opened (once opened, the language associated with a file is remembered). Extensions must be listed without a preceding dot and separated by whitespace. If the same extension is set for more than one language, an "unknown" icon will be shown, and you will be prompted to select one of the appropriate languages before opening the file.

Variables

Variables are expressed as %variable_name or %<variable_name>. Variables longer than one character that were added after jGRASP version 1.4.3 must be expressed as %<variable_name>, and are marked as [new] below.

%<JGRASP_PATHS> [new] - paths set in workspace and project PATH tabs. Workspace level paths are appended to project level paths. In the system compiler environments, this variable is always prepended to the PATH.

%<JGRASP_C_PATHS> [new] - default paths for C, C++, Objective-C, and Ada "generic" compiler environments. These paths will be appended to the PATH when compiling and running using a generic environment. This is currently empty on non-Windows systems and on Windows has the default install bin directories for Cygwin, MinGW, GNUstep, Borland 5.5, and DJGPP, in that order.

%<JGRASP_CLASSPATHS> [new] - classpaths set in workspace and project PATH tabs. Workspace level classpaths are appended to project level classpaths. In the system compiler environments for Java, this variable is always prepended to the CLASSPATH.

%<VIEWER_CLASSPATHS> [new] - classpaths necessary for compiling jGRASP viewer plugins.

%<PYTHON_PATH> [new] - the path to the Python executable if found, blank otherwise.

%<FLAGS> - flags or arguments.

%<ARGS> - same as %<FLAGS>.

%<FILE> - full path to file.

%<file> - filename.

%<BASE> - full path to file without extension.

%<base> - filename without extension.

%<PATH> - full path to directory containing file.

%<EQ> - equals sign.

%<PLUS> - plus sign.

%<SEP> or %\ or %/ - name separator character ( \ on Windows / on UNIX).

%<PATH_SEP> or %; or %: - path separator character ( ; on Windows : on UNIX).

%<A> - "a.exe" on Windows systems, otherwise "a.out".

%<EXE_EXT> - ".exe" on Windows systems, otherwise an empty string.

%<PROJECT_PATH> - path to the directory containing the project, or the empty string if there is no project.

%<JAVA_BIN_DIR> - path to the directory containing the java executable that was used to start jGRASP.

%<JAVADOC_ROOT> - URL of the Java documentation api root, or the empty string if one is not set.

%<DOC_DEST> - documentation destination directory.

%<SRC_DIR> [new] - The project source directory, if one is set, empty otherwise.

%<CLASSES_DIR> [new] - The project classes directory, if one is set, empty otherwise.

%<TMP_DIR> [new] - The project temp directory, if one is set, empty otherwise.

%<DOC_DIR> [new] - The project documentation directory, if one is set, empty otherwise.

%<RES_DIR> [new] - The project resources directory, if one is set, empty otherwise.

%<BIN_DIR> [new] - The project binaries directory, if one is set, empty otherwise.

%<HELP_DIR> [new] - The project help directory, if one is set, empty otherwise.

%<SRC_CLASSPATHS> [new] - The classpath for all Java source files in the project, joined with path separators.

%<TEST_CLASSPATHS> [new] - The classpath for all Java test files in the project, joined with path separators.

%<ALL_CLASSPATHS> [new] - The classpath for all Java source and test files in the project, joined with path separators.

%<PYTHON_PATH> [new] - Path to the directory containing the executable used to open Python files in Windows.

%<TRANSPORT> - JDK jdpa (debug interface) transport appropriate to current OS. This is dt_shmem if available, dt_socket if dt_shmem is not available, and the first transport found otherwise.

%<CHARSET> - The canonical charset name for the file or project, or empty if the default charset should be used.

%<CLASSIC_OPT> - "-classic" on systems where the latest JDK ships with a classic VM, otherwise the empty string.

%<PACKAGE> - (Java) full package name.

%<CLASS> - (Java) full package/class name.

%<class> - (Java) class name.

%<PACKAGE_PATH> - (Java) path to source package root.

%<PACKAGE_CLASSPATH> - (Java) path to class file package root.

%<D_STC> - (Java) "-d" if the source-to-class relative path is not empty, empty otherwise.

%<HTML_FILE> - (Java) full path to temporary html file.

%<html_file> - (Java) temporary html file name.

%<D> - begins and ends a part of the command that is only used when compiler debug mode is on.

%<N> - begins and ends a part of the command that is only used when compiler debug mode is off.

%<I> - begins and ends a part of the command that is only used when a file-level command is executed.

%<K> - begins and ends a part of the command that is only used when a project-level command is executed.

%<EY> - turn on input echo. This is the default mode. In this mode, input in the Run I/O window remains visible after it is entered.

%<EN> - turn off input echo. In this mode, input in the Run I/O window disappears after it is entered. This is useful if the target process will echo input, or if the input should not be seen in the output stream.

%<CP> - turn on pipe connection mode for a command (Windows only). This is the default mode (but the Cygwin compiler environments use %<CY>). In this mode, input and output to the target process will be through pipes. Many Windows programs will buffer output in this mode (Java programs will not).

%<CD> - turn on DOS window mode for a command (Windows only). If on, the target process will always run in a DOS window.

%<CY> - use Cygwin wedge for a command if the target is a Cygwin executable, otherwise use pipe mode (Windows/Cygwin only). If on, a Cygwin target process will be called from a Cygwin-aware native wedge program. This should eliminate output buffering problems for Cygwin applications. For non-Cygwin executables, pipe mode will be used.

%<CYD> - use Cygwin wedge for a command if the target is a Cygwin executable, otherwise use DOS window mode (Windows/Cygwin only). If on, a Cygwin target process will be called from a Cygwin-aware native wedge program. This should eliminate output buffering problems for Cygwin applications. For non-Cygwin executables, DOS window mode will be used.

%<CC> - turn on console connection mode for a command (Windows only). If on, input to the target process will be through a console, while output is through pipes. This can eliminate I/O buffering problems seen when input is through a pipe. It does fix buffering problems on executables compiled with some old versions of Cygwin gcc and g++. On VC++, Borland bcc, and new Cygwin compiled executables, it makes buffering worse (block buffered instead of line buffered output). It will cause some jvms to crash.

%<ND> - Run in Windows Console setting will be ignored on Windows. This is used for the integrated Java debugger, which currently must use the Run I/O window for I/O.

%<V1> - variable specified in environment.

%<V2> - variable specified in environment.

%<SAVE> [new] - true if modified files should be saved before execution when autosave is on. This is redundant for compile commands.

A %<FLAGS>, %<ARGS>, %<FLAGS2>, or %<ARGS2> variable must be surrounded by whitespace; the others need not be. To put a percent symbol in a command, use %%. To put a double quote in a quoted string, use %'.

Variables that are related to files, paths, and classes may be prepended by MAIN_ or main_ . In that case, the main file will be used in the substitution, or if a main file was not specified, the current file will be used.

Variables that are related to files, paths, and classes may be prepended by PROJ_ or proj_ . In that case, the project file will be used in the substitution if the action has a related project, otherwise if a main file was specified it will be used, otherwise the current file will be used.

Variables that are related to full files and paths may be prepended by REL_ . In that case, a file and path relative to the working directory will be used.

Project path variables may be prepended by RELE_ . In that case, a relative file or path that ends with a path separator will be used, unless the path is the working directory, in which case an empty string will be used.

CSD Page

CSD generation settings.

Show Unit Symbols - if on, package/method/function symbols are shown.

Show Boxes - if on, boxes are drawn around major code structure headings (packages, methods, functions, etc.).

Force Newlines - if on, each statement is forced to a new line.

Auto Indent - if on, hitting return will insert whitespace equal to the CSD, space and tab indentation of the previous line.

Show Data Syms. - if on, data and type symbols are shown.

Intra-Stmt. Align - if on, parenthesis and assignment symbols are aligned.

Indent Braces - if on, curly braces in C, C++, and Java are indented to match the enclosed block.

Soft Tabs - if on, spaces are used instead of tabs, for the tab key, block indent, and auto indent.

Flashing Cursor - if on, the CSD Window cursor will flash when the window has focus.

Brace Matching - if on, matching braces, brackets, or parentheses will be highlighted when the mouse is placed over one of the matching pair; if off, this will only happen when the ctrl key is held down.

Unbuffered Display - if on, display in editing windows and message windows will be unbuffered. This should allow faster scrolling and repainting, but may cause some flicker, flashing, or "waving" during some editing operations. We will be working to reduce these problems as much as possible in future jGRASP releases.

Tab Size - width of a tab in characters. For variable-width fonts, the width of a "W" is used.

Colors Page (workspace settings only)

Colors for lexical types, CSD and background color, and message and I/O window colors. Click the Use Default checkbox off and click on the color square to change the color.

Font Page (workspace settings only)

Font Properties - font attributes (bold and/or italic) for lexical types in the CSD and message windows. Note that on some systems and with some fonts, bold and italic fonts will not align with the plain font and/or each other, even for fixed-width fonts.

Font Scale (all fonts) - scale factor for all fonts (CSD, menus, labels etc.) in jGRASP. This is quite useful for presentations or systems on which the default font size is too small. For the Nimbus Look & Feel, this does not work because that Look & Feel does not scale well.

CSD Font - font to use in CSD and message windows.

Antialias - if on, CSD and message window fonts are antialiased. Antialiasing generally improves the appearance of text at higher resolutions (or large font sizes), but at low resolutions it may make text harder to read.

CSD Font Size - base size of the CSD window font.

Message Font Size - base size of the message and I/O window font.

Font Size Page (project and file settings)

CSD Font Size - base size of the CSD window font. Using different font sizes in different windows may consume a lot of memory.

Sources Page (Workspace and Project Settings Only)

Allows the search path for jGRASP to be specified. This path will be used for click-to-error in the jGRASP message windows as well as for finding classes shown in the call stack of the integrated debugger for Java. These are used when the message or call stack reference contains a relative path name or a Java class name. They are searched in order. If this is not set, only the working directory for the command that produced the message or the source directory for the associate project will be searched. If this is set, and one of the paths is "working directory", the working directory will be searched at that point. In most cases you will need to include "working directory" as one of the paths, probably the first.

Paths are entered one per line, and must be absolute.

This can be used, for example, to get click-to-error to work for JDK classes in Java stack dumps, if you have the JDK sources. In that case, the root of the JDK source tree (the directory containing the java, javax, etc. directories) should be on one line, and "working directory" on another.

PATH Page (Workspace and Project Settings Only)

Allows you to add to the system PATH and CLASSPATH for compile and run commands, and to the Plugins path (workspace level only) for finding viewer nd tool plugins. The project settings will take precedence over those at the workspace level. The compiler environments delivered with jGRASP will prepend these paths to the system PATH and CLASSPATH before compiling or running.

Paths are entered one per line. Appropriate separators will be added automatically.

Charset Page (Workspace Settings Only)

Allows you to specify the charset used by default for file contents (Default Charset) and for I/O to your programs (I/O Charset). If you want to ensure that your source files will look the same anywhere, it's best to used the US-ASCII charset, which is a subset of most others. Otherwise, for cross-platform compatibility, UTF-8 is a good choice (it is the default on Linux, and for some IDEs when running on any system).

---

Compiler Environment Dialog

This dialog allows a compiler environment to be created, edited, or viewed. These environments specify compile and run commands, working directories, and error formats.

• Name Field - name of the environment. Not editable for system environments.
• Copy Button - copy the environment to the clipboard.
• Paste Button - paste the environment from the clipboard.
• Export Button - save the environment to file.
• Import Button - load the environment from file.
• Commands Page
• Parsing Page
• Macros Page
• OK Button - save the environment and close the dialog.
• Save Button - save the environment without closing the dialog.
• Clear Button - clear all the settings.
• Reset Button - reset the dialog to the current state of the environment.
• Cancel Button - close the dialog without saving the environment.

---

Commands Page

This page specifies settings for Make, CCompile and Link, Compile, Check, Run, Debug, and (for Java) Run Applet and Debug Applet commands. For each command a working directory and error format can be specified. If a compile or run command is empty, that command will not appear on the Build menu of the CSD window, and the icon will not appear on the toolbar.

A variety of execution-time variables may be applied to commands and directories. Also, two static variables, %<V1> and %<V2>, can be specified at the bottom of the page.

Environment variables can also be modified.

Whitespace separates arguments in commands. Use double quotes to specify an argument containing whitespace. Use %' (percent-single quote) to include a double quote in a quoted argument. Any variable can also be used in a quoted argument, and %% (percent-percent) must be used to include a percent symbol.

Command specifies the command. All variables may be used.

Directory specifies the working directory for the command. If left blank, the directory containing the file will be used. %<PATH>, %<base>, and for Java, %<PACKAGE_PATH> and %<PACKAGE_CLASSPATH> variables may be used here.

Error Format specifies the error format for the command. The format string begins with a list of target flags, followed by a dash. The rest of the string is a Java regular expression. See the Java Pattern API for a description of the regular expression format.

The target flags are:

For click-to-error to work, the numbers of target flags must be equal to the number of matching groups in the regular expression. If a filename or class (possibly in combination with an unqualified file name) is matched and the corresponding file exists, a click will open the file. If the start line is matched, that line will be highlighted. If the start and end lines and columns are matched, that piece of text will be highlighted. If a filename and class are matched, the filename will be tried first. If the same target type matches multiple times, the last match is used. Unmatched groups are ignored, so you can use or'ed expressions and repeated target flags to match multiple possible formats. No error message is reported if the format is bad, or the number of target flags does not match the number of groups. On the control panel Tools menu, there is a testing tool for pattern matches.

As an example, "f1-(\S(?:\s*\S)*):(\d+):.*" will match the file and line number of a GNU-style error message with a single line number only. The regular expression reads as: a matching group containing (a non-whitespace character followed by any number of non-matching groups consisting of any number of whitespace characters followed by one non-whitespace character); followed by a colon; followed by a matching group consisting of one or more digits; followed by a colon followed by anything. In other words, "filename:line_number:other_text", where filename must begin and end with non-whitespace characters and be at least one character long, and line_number consists of one or more digits.

The following constants may also be used as error formats:

• GNU - GNU standard error format, as described here.
• Java_Stack - Java stack dump line.
• Java_Stack_or_jdb - Java stack dump line or jdb location.
• J2ME_Stack - J2ME stack dump line.

Environment allows environment variables to be changed and special jGRASP variables to be set. Variables are set one-per-line, using the following format:

For now, the only special variables are NOT_FOUND_MESSAGE, which specifies the message to display when the compiler is not found, ADD_EXE_PATH, which add the directory containing the executable to the path for Windows only, ADD_APPLETVIEWER_CLASSPATH, which adds -J-cp -J_CLASSPATH_ (where _CLASSPATH_ is the run-time CLASSPATH) as the first and second command line arguments, and ADD_EMULATOR_CLASSPATH, which adds -cp _CLASSPATH_ (where _CLASSPATH_ is the run-time CLASSPATH) as the first and second command line arguments.

Remember to add a path separator when prepending or appending to a path, like "PATH+=C:\newpath;" on Windows or "PATH+=/usr/local/newpath:" on UNIX/Linux, or "PATH+=/usr/local/newpath%<PATH_SEP>" (%; and %: are equivalent to %<PATH_SEP>) for either.

All variables may be used, so you'll need to escape "%" with "%%". All whitespace is significant, so don't leave space before the end-of-line or within the command unless you mean it to be there. For example, "VAR = VALUE" will set "VAR " (VAR followed by a space) to " VALUE" (VALUE preceded by a space).

You can have a plus sign at the beginning of a value by using the %<PLUS> or %+ variable. For example "VAR=%+val" will set "VAR" to "+val". In most environments, equals signs can not appear in environment variable names, but for completeness, you can use %<EQ> or %= to include an equals sign (this will most likely produce unexpected results).

By default, settings apply to all commands. You can change the commands they apply to using "-Command", "+Command", and "Command". For example "-Run" will make the following settings not apply to the run command, "+Run" will make the following settings apply to run, and "Run" will make the following settings apply only to Run. These commands can be grouped on a line, separated by whitespace. Use the exact labels in the dialog for command names, but for Run Applet and Debug Applet, use "Run_Applet" and "Debug_Applet" (replace space with an underscore). To turn all commands on or off, use "+All" and "-All".

For example: add C:\mypath to the path but not for run or debug, set DEBUG_TEST to 1 for compile only.

By default, settings apply to file-based and project-based commands. You can change this using "File", "Project", and "ProjectOrFile" to make the following settings apply to files only, projects only, or both, respectively.

---

Parsing Page (Java, C, C++, Objective-C, and Python only)

Parsing options for some languages. These apply only to CSD generation, not to compiling. Those for for C, C++, and Objective-C are described below. For other languages, the settings involve language version compatibility and are fairly self-explanatory.

Include Path - search path for include files. The directory containing the file is always searched (last).

Include Files - all, none, or only local include files may be parsed. Local includes are defined as those include by #include "filename" rather than #include <filename>. Include file parsing is necessary for CSD generation if the include files contain unstructured macros (macros that when used, do not look like legal C or C++ code) or partial code structures. Parsing include files can make CSD generation slow, so it should be turned off if unnecessary.

Expand Macros - if true, macros are expanded during CSD generation. This may be necessary for unstructured macros, and for others, part of the CSD structure for the substitution result may be shown if this is on.

Allow GNU Extensions - if true, the GNU __attribute__ keyword is handled. It will not be colored. Most other GNU extensions are supported regardless of this setting.

Use Alternate Tokens - the C++ language allows alternate tokens such as "<%" for "{".

Allow C++ Comments - allow // comments in C. This can not be done by default because of things like:

---

Macros Page (C, C++, and Objective-C only)

Specifies macros that are pre-defined for CSD generation of C, C++, and Objective-C. By default, _GRASP_IGNORE is defined: by using #ifndef _GRASP_IGNORE, blocks of code that can't or shouldn't be involved in CSD generation can be ignored.

---

Print Settings Dialog

This dialog is used to set properties related to printing. The OK, Apply, Reset, and Cancel buttons operate in the same way as those of the CSD window settings dialog. The Units combo box changes the displayed units for items in this dialog.

• Common Page
• CSD/Messages Page
• UML Page

---

Common Print Settings Page

These settings apply to both CSD and UML printing.

Standard Paper Sizes - choosing an item from this pulldown list will set the paper width and height.

Paper Width / Height - these are ignored for native Windows CSD printing, and can be set in the Windows print dialog (if allowed) in that case.

Horizontal / Vertical DPI - the horizontal and vertical resolution of the target device or printer. If this is not known, choose a high density (the default is 300x300dpi). If the resolution set here does not match the resolution of the target device or printer, the alignment of the printout may be off very slightly for all types of printing. The error can be 1 pixel per character, which at high resolutions is not noticeable. For Java printing, the resolution is also used to build the CSD characters, so the CSD may look chunky or asymmetrical if the resolutions are not correct.

---

CSD/Messages Print Settings Page

Color - if on, printing will be in color.

Page Numbers - if on, the page number is printed on each page.

Filename Header - if on, the filename is printed at the top of each page.

Break Pages on Form Feed - if on, form feed characters (hex code 0C) will cause page breaks in the printing. If off, these characters will be printed in the text font.

Landscape - if on, printing will be in landscape mode. This is ignored for native Windows printing, and can be set in the Windows print dialog in that case.

Book Format - if on, left and right margins will alternate. This is useful if the printouts will be bound.

Left Page First - if on and book format is on, the first page printed will have reversed margins.

Left / Right / Top / Bottom Margin - page margins.

Gutter - spacing between columns if more than one column is used.

Line Spacing - the CSD will stretch when line spacing is increased. At an aspect ratio of 3 or above, the CSD will lose its symmetrical appearance.

Columns - allows multiple columns of text per page.

Font Size - the size of the printed font.

Header - text for a header: to be printed at the top of each page.

Font - the printed font. Note that Courier is always used for "Print To File (PostScript)" regardless of this setting.

---

UML Print Settings Page

Margin - the same margin is used on all four sides.

Multi-page Overlap - for multiple-page printouts, the pages must be overlapped by this amount to align them properly. This makes it easier to assemble multiple-page printouts.

Landscape - if on, printing will be in landscape mode.

Maximum printed width, height - if the printed image exceeds this size, you will have the option to scale to this size.

Horizontal and vertical image alignment - alignment within the printed page or pages.

UML Diagrams

jGRASP can produce a UML diagram for Java code. The diagram is generated for classes in the source, class, and JAR files in the current project. These diagrams are generated directly from the class (or JAR) files. If a class file is missing but the source is available, disconnected class nodes will be shown if the source can be parsed, while a <source.java> node will be shown when the source can not be parsed.

Object instances can be created and static methods invoked directly from the UML diagram, by using the context menu. Objects created in this way are put on the debugger workbench, and can then be operated on in various ways. For information on the workbench see Integrated Java Debugger and Workbench.

---

UML Window

This window displays the UML diagram.

• File Menu
• Edit Menu
• View Menu
• Build Menu
• For other menus, see Control Panel

• Diagram Display
• Editing the Diagram
• Info Window
• Goto Window

---

File Menu

These are additional menu items available when a UML window is active. For the base set of menu items, see control panel file menu.

Close - closes the UML window.

UML Print Settings - opens a print settings dialog for workspace or project level settings, and selects the UML tab.

UML Print Preview - preview the printout. The preview should be a close approximation of the printed result, but there may be minor differences because of scaling.

UML Print - print the diagram. The scale of the printout is based on the scale of the image. 100 pixels of image will be 1 inch on the printout.

Escape Virtual Desktop / Enter Virtual Desktop - takes the UML window in and out of a virtual desktop.

Raise/Lower - in a virtual desktop, move the UML window to the front if it is not on top. If it is on top, move it to the back. Outside a virtual desktop, move the UML window to the back.

Exit jGRASP - quits the application. If a compile process is active and there are modified files, this will not be allowed, since the old files are backed up before compiling, and restored afterward - this is not a concern if the Auto Save setting is checked (it is checked by default), in which case all files are saved before compiling.

---

Edit Menu

These are additional menu items available when a UML window is active. For the base set of menu items, see control panel edit menu.

Layout

Delete Selected Edge Bends - the tree layout algorithms will insert bends in inheritance edges. This will delete them.

Remove From Project - removes selected or unselected files from the project. That is, for each selected or unselected object in the diagram, the source file from which that object was generated will be removed from the project. Also removes any project documentation corresponding to Java source files that are removed. Note that external objects do not have a corresponding source file.

Add To Project - add selected or unselected external object files to the project. All package root directories for files in the project will be searched, and if exactly one source file for a particular external object is found, that file will be added to the project.

Select - extend the current selection by selecting any objects related in a particular way to the currently selected objects. For example, Recursive Relations will select all objects directly or indirectly related in any way to the currently selected objects.

---

View Menu

Visible Objects - controls the types of objects that are shown. For example, you can hide non-public objects, or external objects (objects that are not in the project).

Visible Dependencies - controls the types of dependencies that are shown. For example, you can limit the view to inheritance dependency edges only.

Hide / Show - hides selected or unselected objects, or shows all objects.

Info - controls various properties of the info display. If Show Inheritance Within Project is on and a class is selected, the info window will display accessible fields and methods inherited from classes in the project, but not from other classes.

Legend - controls various properties of the legend display.

Appearance - controls various visual properties of the diagram, such as bold fonts and borders, and antialiasing.

---

Build Menu

Compile All - using known dependency information, attempts to recompile all Java files in the project using the fewest number of compile commands possible.

Clean - removes all class file from a Java project. Only class files referenced by current source files will be removed. Those corresponding to classes that no longer exist in the source, and those with no corresponding source, will not be removed.

Debug Mode - if on, compile in debug mode. This is a global setting in jGRASP.

Enable Assertions - if on, assertions will be enabled for Java compilation. This is a global setting.

Run-related items here have essentially the same functions as in the CSD window Build Menu, except that a main() method or an applet will be searched for in the Java classes. If the project contains more than one main() or more than one applet, you must select one of them.

Run Topmost - if on, windows created by your code will be in "always on top" mode. If your application needs to control the Z-order of windows, or if it launches other gui applications, then you may want to turn this off.

Focus to Run I/O Window When Running - if on, keyboard focus will move to the Run I/O window when running.

Java Workbench

---

Diagram Display

This window displays the UML diagram. A legend shows the meanings of the various object colors and edge styles and colors. Objects that need to be compiled based on source and class file modification times are shown with red crosshatches. Objects with dependencies that need to be compiled are shown with red single hatches (diagonal lines).

The object labels display the class name and package name (if any) and the generic type parameters (if any). If the class is abstract, the class name is italicized in the label. Unparsable source files are shown as objects with the label format <source.java> .

A scroller window at the upper left allows the view to be scrolled quickly.

A scale control allows the magnification of the view to be changed. Due to uneven scaling of fonts, the spacing between objects may change slightly as the scale is changed.

Objects can be selected using the mouse. Left click on an object to select it. Left click and drag a selection rectangle in the window to select multiple objects. Hold down the shift key while selecting to add to the current selection. To select the reverse direction of bi-directional edge, click it again.

When an edge is selected, the dependencies it represents are shown in the info window. Only uses of fields, methods, and constructors of the class are shown. Uses of the class as a whole, for example as a method parameter type, as a field type, or in a cast, are not shown.

When an object that is a part of the project is selected, its members (fields and methods) are shown in the info window.

---

Editing the Diagram

To select objects: click the left mouse button on an object. Click the left mouse button in the background and drag the selection rectangle to select multiple objects. To toggle the selection, use Ctrl-left click or on systems where Ctrl-click brings up the context menu, Shift-right click (Shift-Meta- click on one button Mac systems).

To move objects: select then drag one or more objects with the left mouse button.

To move/remove an edge bend: select the edge, then left click and drag the bend. Hitting the delete key while dragging will remove the bend.

To add an edge bend: left click on the edge while holding down the Shift key.

---

Info Window

This window displays the fields, constructors (actually <init> methods), and methods for the currently selected edge (dependency) or node (class or interface). For dependencies, only uses of fields, methods, and constructors of the class are shown. Uses of the class as a whole, for example as s method parameter type, as a field type, or in a cast, are not shown.

Primitive types are shown with a triangle icon, objects with a square, and constructors and methods with a CSD "method" unit symbol.

These are the actual dependencies or members from the class file. Some may be generated implicitly, as ("string" + int_variable) will use several StringBuffer methods. Others may be entirely synthetic, such as the "access$" methods used to access private members of a class from its inner class and vice versa. If the "real" dependency behind a synthetic method can be determined, it will be shown, with the synthetic reference name noted at the end. Synthetic methods for a class are shown with a leading asterisk, as *someMethod(). Synthetic classes and synthetic methods of a class or interface are not shown by default. Synthetic methods can be shown by changing the View > Info > Show Synthetic Methods setting. The display of synthetic classes is controlled by a setting in the UML settings dialog. If shown, synthetic class names also have a leading asterisk.

Double clicking on an item in the list will take you to the first/next definition or use in the source file, if known. All uses will be highlighted. A popup menu (right click on most systems) provides several UML-to-source navigation options as well as the ability to view documentation if it has already been generated. Note that the List Uses option in this list will work even if the source file is not known. For a method, the "definition" is the first executable line of the method. For a field, the definition will show up as a use if there is an initializer, otherwise it is not possible to navigate to it. If the class file has line numbers stripped, the navigation will not work.

---

Goto Window

This window displays all the nodes (objects) currently in the diagram. Clicking on one will center the diagram on that object. The intention is to make navigating a large diagram easier.

---

UML Settings Dialog

Settings for the UML diagram. All of these settings take effect when the diagram is updated.

Exclude By Type of Use - external objects (dependencies of objects in the project that are not themselves in the project) can be left out of the diagram.

Exclude By Type of Class - JDK classes and interfaces, just the class java.lang.Object, and synthetic classes (those generated by the compiler that don't correspond to any source code class), can be left out of the diagram.

New Node Layout - specifies which layout is applied to objects as they are added to the project.

Viewers and Viewer Canvas

The jGRASP viewers provide various ways of displaying and interacting with objects and primitives at runtime, during debugging or during a workbench or interactions session. The viewers update automatically at each breakpoint or step in the program, and after a workbench or interactions operation is processed.

The jGRASP viewer canvas provides an easy way to group viewers and to save viewer configurations. In future jGRASP releases, the canvas will also allow dependencies between objects to be displayed.

In order to launch a viewer, any object or primitive in the jGRASP debug Variables tab, Eval tab, or Workbench tab may be dragged out (using click and drag with the mouse). Releasing the value on a viewer canvas will add a viewer for that value to the canvas, while releasing it in most other places will open a stand-alone viewer dialog. Most objects may be viewed by name or by value. By default, dragged viewers will be dropped by name if possible, while holding down the control key will cause them to be dropped by value. Viewers may also be launched by using the context (right click) menu on a debugger value.

• By Name and By Value Viewers
• Viewer Scope
• Subviewers
• Language Extensions
• Viewer Settings
• Viewer Selection and Types
• Using the Viewer Canvas
• Using "Run in Canvas"
• Creating Custom Viewers
• Canvas Exclusions Dialog

---

By Name and By Value Viewers

For "by name" viewers, the displayed value is determined by evaluating an expression, which may be a name or a more complicated expression, such as a method invocation or a general expression from the Eval tab. These viewers also may carry a scope, and if so will only be evaluated when the viewer is in that scope. Some values, such as values dragged out from other viewers, may not be viewed by name. When expression evaluation in a "by name" viewer results in an error, an error message will be displayed and the previous evaluation result will be displayed.

For "by value" viewers, the displayed value is fixed at the time the viewer was created, and will not change (though its internals can change). These viewers are each assigned a name which may be used in workbench or interactions expressions. By value viewers in a viewer canvas are not saved with the canvas and do not persist between debugger sessions.

---

Viewer Scope

Most "by name" viewers have an associated scope, which is the scope that was in effect when they were created. Values from the Eval tab do not have an associated scope and evaluation will take place in any scope. For simplicity, the scope consists of the method declaring type, method signature, and call stack depth, so it is not a true and complete scope. When the current scope does not match the viewer scope, an "out of scope" message will be displayed, and the value that is the result of the most recent evaluation in a valid scope will be displayed.

For viewers in a canvas, the use of scope may be modified. The menu on each viewer frame allows the scope to be set to "Full", "Recursive", or "None". With "Recursive" set, the depth value of the scope will be ignored. This is useful for viewing a field or local variable at any depth in a recursive algorithm. With "None" set, the "by name" expression will be evaluated in any scope.

---

Subviewers

For many viewers, selecting a sub-component in the display will open a viewer for that component in a pane at the bottom of the canvas window or viewer dialog. This can be used to quickly view the details of various sub-components.

---

Language Extensions

In order to restrict the display of values to a finer degree than method scope, the Java language has been extended for use in viewer expressions. These extensions may also be used in eval expressions (where they may be useful) and in interactions and workbench expressions (where they would rarely be useful). When the expression for a "by name" viewer uses such an extension, a button on the viewer settings allows the full expression (including the extension code) or the short expression (omitting the extension code) to be displayed.

The "local" extension takes the form `local` name or `local type` name. For example, in `local` x, "x" will only be evaluable when there is a local variable named "x", regardless of its type, while `local int` x will only be evaluable when there is a local variable named "x" of int type. This allows a local variable to be displayed, without the viewer changing its "meaning" when the variable is out of scope within the method and a field with the same name or local variable with the same name and different type is in scope.

Other extensions are planned for a future release.

---

Viewer Settings

General and viewer-specific settings are shown at the top of a viewer dialog. On the canvas, these are available through the "Viewer Settings" item on the viewer frame menu. General settings common to all viewers and settings for the basic viewer are described below.

Type - the effective declared type of the value. This defaults to the actual declared type. Changing this allows the value to be displayed as if it had a different declared type. This is useful mainly for the detail viewer, where color is used to indicate the relationship between a field's type and the object's declared type.

Viewer - allows the particular viewer that is used to display the value to be selected.

Accessibility Context - for the detail viewer, the effective context of the value. This defaults to the current context. Changing this allows the value to be displayed as if it was in a different code context. This is useful because inaccessible and non-visible fields are indicated graphically in the detail view. Thus, changing this answers the questions "Can I access this field or array element from the selected context?" and "Do I need one or more casts to access this field or array element from the selected context?".

---

Viewer Selection and Types

The "Viewer" menu on a viewer dialog allows different viewers to be selected, so that the value can be viewed in various ways. On the canvas, the menu on each viewer frame also allows the viewer to be selected. The most commonly available types of viewers delivered with jGRASP are described below.

Detail Viewer: Available for all values. Displays the value in an expandable tree, identical to the way it is displayed in the debug Variables, Workbench, or Eval tab. Sub-values may be dragged out of the tree.

Basic Viewer: Available for all values. Displays the non-static fields of an object, the elements of an array, and a text description of a primitive. Sub-values may be dragged out.

Presentation String: Available for all values. Displays the value using its toString() value or primitive string value, or as a comma separated list of array values. Specific types, such as java.util.List, may also be displayed in useful ways rather than by their toString() values.

Numeric Viewer: Available for primitive numeric types and numeric wrapper objects. Displays integral values in various bases and floating point values showing the details of how the floating point value is determined from the binary representation.

Formatted and Formatted Wrapping Viewers: Available for strings. Displays the string in formatted form (as it would be printed), with or without line wrapping.

Source Format Viewer: Available for strings. Displays a source code representation of the string.

Monitor Info Viewer: Available for all Objects. Shows the owning thread and waiting threads if the Object is used as a monitor (synchronization object). This can be useful in tracking down deadlocks and other threading problems.

Presentation Viewer: Available for arrays and collections. Shows the internal representation of the structure. Typically, only the portion of the structure that is visible on screen is updated, so this viewer is useful for structures that may be too large to view efficiently using the Structure Identifier Viewer. Sub-values can be selected and viewed in the sub-viewer pane, or dragged out (but in most cases only by value).

Collection Elements and Array Elements Viewers: Available for arrays and collections. Displays the toString() or primitive string value of the elements in scrollable list form. Typically, only the portion of the structure that is visible on screen is updated, so this viewer is useful for large structures. Sub-values can be selected and viewed in the sub-viewer pane.

2D Array Elements Viewer: Available for 2D arrays. Displays the toString() or primitive string value of the elements in table form. Typically, only the portion of the structure that is visible on screen is updated, so this viewer is useful for large structures. Sub-values can be selected and viewed in the sub-viewer pane.

Bar Graph Viewer: Available for all arrays and lists but only useful for those containing numeric values. Displays the numeric values as a bar graph. This is especially useful for visualizing sorting algorithms.

Image Viewer: Available for Java images and image icons. Displays the image.

Color Viewer: Available for java.awt.Color. Displays a swatch of the color. The viewer settings also show the rgb values.

Component Viewer: Available for java.awt.Component. Shows an outline of the component and its sub-components. Hovering the mouse over a displayed sub-component will show the type, position, and size of each component in the ancestor chain from that sub-component to the value being viewed. This viewer is useful in diagnosing layout problems and understanding layout behavior. Unlike most other viewers, this viewer updates periodically, rather than only at debugger breakpoints and steps or after a workbench or interactions operation.

Structure Identifier Viewer: Available for all Objects, but only useful for those that are linked or array-based structures. Attempts (successfully in most cases) to identify the structure and display its internal representation. Sub-values can be selected and viewed in the sub-viewer pane, or dragged out (but in most cases only by value). This viewer evaluates the entire structure on each update, and so it may not be practical for very large structures. For more information, see Structure Identifier Viewer.

---

Using the Viewer Canvas

Each viewer on the canvas is displayed within a viewer frame. This frame will be invisible unless the viewer is selected. When selected, the frame can be used to move, resize, or scroll the viewer. It also provides a label icon that can be used to drag out a copy of the viewer, and a menu for changing viewer properties.

By default, the viewer size is determined automatically based on its contents. Once the viewer frame is resized by dragging, it will retain that selected size. The "Auto Size" item on the viewer frame menu will return a viewer to automatic sizing. When a viewer does not fit entirely within a frame and is not selected, dashed edges indicate the edges at which the view is cut off.

By default, viewers are displayed on a white background and with a thin black border. The viewer frame menu allows viewers to be made transparent, in which case they will be displayed without a border and with a transparent background. The selected viewer is always shown with a white background.

• Viewer Frame Menu
• File Menu
• Edit Menu
• View Menu
• Run Menu

Viewer Frame Menu

This menu is available through the button on the upper right of the frame for a selected canvas viewer.

Viewer - allows a particular viewer to be selected.

Edit Expression/Scope - allows the expression and scope for by-name viewers to be directly edited.

Viewer Settings - pops up viewer-specific settings.

Invoke Method - for viewers on objects, brings up a dialog that allows a method to be invoked on the object.

Viewer Info - displays information about the currently selected viewer.

Transparent - makes the viewer transparent or solid.

Scope Test - allows the type of scope evaluation to be changed.

Move to Back - moves the viewer behind all others.

Auto Size - returns the viewer to "auto size" mode if it has been manually resized.

Remove - removes the viewer from the canvas.

File Menu

New Canvas - opens a new, empty canvas.

Clear - removes all viewers from the canvas.

Open - allows a viewer file to be opened.

Close - closes the canvas window.

Save - saves the canvas file.

Save As - renames and saves the canvas file.

Backup As - saves the canvas under another filename without changing the current filename.

Escape Virtual Desktop / Enter Virtual Desktop - takes the canvas window in and out of a virtual desktop.

Raise/Lower - in a virtual desktop, moves the canvas window to the front if it is not on top. If it is on top, moves it to the back. Outside a virtual desktop, moves the canvas window to the back.

Edit Menu

Add Text Box - allows a box that displays text or html to be added to the canvas. This may be used for notes or instructions.

Add Expression Viewer - brings up a dialog that allows a by-name viewer to be directly created.

Change Class and Method Names - brings up a dialog that allows class and method names to be changed in all scopes and expressions used in the canvas.

Exclusions - brings up a dialog that allows class and method exclusions to be set. These are classes and methods that will be skipped when the "Play" or "Step In" functions are used. For more details see exclusions dialog.

View Menu

Debug Controls - shows or hides the debugger controls on the canvas toolbar.

Show Runtime Types in Viewer Labels - if on, for each viewer the runtime type of the object or primitive will be shown in the viewer label.

Grid - allows grid settings to be changed, snap-to-grid behavior to be turned on or off, and grid display to be turned on or off.

Transparency - allows all viewers on the canvas to be made transparent or solid.

Run Menu

Run - starts the debugger on the class or main class associated with the viewer. The debugger will stop at the first valid line in the entry method (main(), start(), etc.).

Play - turns on autostep and begins repeatedly stepping in to the code.

Pause - turns off autostep.

Stop - end the debug session.

---

Using "Run in Canvas"

The "Run in Canvas" items on the build menu for a Java file and on a canvas window allow the debugger to be launched and an associated canvas to be opened in one step, or the debugger to be launched with a file or project associated with the canvas.

When "Run in Canvas" is used, the debugger will automatically stop at the program entry point. No breakpoint is necessary. The program will also stop at its endpoint, so that the canvas will remain active when the program is finished, until you actively end it.

The association between a file or project and canvas is purely by name. If the file is not in a project, then the canvas file must be in the same directory and named base.jgrasp_canvas_xml or base.*.jgrasp_canvas_xml, where base is the base file name (MyFile for MyFile.java) and * is any character other than a dot. When the file is in a project, the project name may also be used as the base name if the canvas file is in the same directory as the project file. When the project has a canvas directory, any filename ending in .jgrasp_canvas_xml may be used for canvas files in that directory. Files in the project or canvas directory with a base name of one of the files in a project will also be associated with that particular file. In that case, if the file has a package then the base name must be preceded by the package name, with underscores replaced by double underscores and dots replaced by underscores, followed by another underscore. So for SomeClass.java with package SomePackage.SubPackage, the file-associated base name would be "SomePackage_SubPackage_SomeClass". Note that the package name is not a part of the base name when the canvas file is in the same directory as its corresponding source.

The file association rules above may lead to cases where multiple sources and/or projects are associated with a canvas. In that case the project and source associated when the canvas was opened, if any, will be used. This information will not persist between jGRASP sessions.

A "Run in Canvas" on a java file will start the debugger and open an associated canvas. If no associated canvases are found, an empty canvas will be opened. If multiple associated canvases are found, you will be allowed to select among them.

A "Run in Canvas" on a canvas window will find the associated Java file or project, and start the debugger. If no associated file or project is found, an error message will be displayed.

---

Creating Custom Viewers

Users are encouraged to experiment with creating their own viewers. Because the viewer API has been rapidly changing, we have not yet made it public. If you want a copy of the API documentation, let us know. Source code for the viewers included with jGRASP may be found in the extensions/viewers directory of the jGRASP installation. The easiest way to create a custom viewer is to begin with a copy of one of our viewers.

Viewer classes may be placed in an "extensions" subdirectory of any plugin directory. The plugin directories may be viewed and edited through Settings > PATH/CLASSPATH > Workspace on the Plugin Paths tab. Placing custom viewers within the jGRASP distribution is not recommended, since these may be overwritten when jGRASP is updated.

Viewer code is multi-threaded and care must be taken to write thread-safe code. Viewers are updated on the debugger thread. All display data should be saved during an update, and then used during display which takes place on the AWT event dispatch thread (EDT). Care must be taken not to modify the gui on the debugger thread or to use debugger values on the AWT EDT.

Viewers may be modified and tested incrementally without restarting the debugger. Tools > Reload Plugins will reload all plugins including viewers. Any viewers created after that will use the most recent viewer class file. Old viewers will persist, though they may crash if the viewer consists of multiple class files and if some have not yet been loaded.

---

Canvas Exclusions Dialog

The exclusions dialog allows class and method exclusions to be set. These are classes and methods that will be skipped when the "Play" or "Step In" functions are used. Each exclusion in the list may be checked on or off to make it active or inactive.

Add From List - brings up a list of potential exclusions for classes and methods associated with the current project or class file. One or more items in the list may be selected and then the "Add Selected" button will add them to the exclusions dialog list.

Add - brings up a dialog for adding an exclusion to the list. The exclusion is entered as a fully qualified class name and method description in source code format. The class name may be "*" to exclude a method for all classes. If the method description is left blank, all methods in the specified class will be excluded. If the method description is a method name only, then all methods with that name will be excluded. If the method name is the same as the class name or is "<init>", all constructors will be excluded. If the method name is "<clinit>" the class initializer will be excluded.

Edit - brings up a dialog that allows the selected exclusion to be edited. See "Add" above for a description of the accepted exclusion formats.

Remove - removes the selected exclusions.

Copy - copies the selected exclusions to the clipboard.

Paste - pastes exclusions from the clipboard.

Sort - sorts exclusions by class name, secondarily by method name, and lastly by method signature.

OK - applies exclusions and closes the exclusions dialog. Changes will take effect the next time "Play" or "Step In" is used in the canvas.

Apply - applies exclusions. Changes will take effect the next time "Play" or "Step In" is used in the canvas.

Cancel - cancels any changes made and closes the exclusions dialog.

Tool Plugins

jGRASP is delivered with several tool plugins. Installation of each tool and use of the plugin are described below.

Most of these tools will be automatically recognized by jGRASP if they are installed in default or common locations. To assist in recognition, you should shut down jGRASP before installing a tool, and restart it after.

Common locations in which jGRASP will search for tools on Windows are: root of the C drive, Program Files and Program Files (x86) directories, documents folder, and desktop. On Mac/Linux/UNIX the common locations are: user home directory, user_home/Desktop, user_home/bin, /bin, /usr/bin, and /usr/local/bin.

If you are interested in creating your own tool plugin, you can use the source code in the extensions/tools directory of the jGRASP installation as a guide. Source code for all of the tool plugins delivered with jGRASP is included. A public API is not currently available for download since the tool system is not very comprehensive. If you are interested in creating a tool plugin, contact us and we'll send you the current API and possibly assist with any functions that you need added to the API.

• Checkstyle
• DCD
• FindBugs
• JUnit
• Web-CAT

---

Checkstyle

Checkstyle is a development tool that aids in enforcing coding standards for Java source code. It can be configured to support almost any formatting standard, and can also check for many design issues, such as local variable names that hide fields or excessively long methods.

Consistent source code formatting aids in readability. Similar indentation, spacing, and identifier naming across a project allows one to scan different parts of the code without having to cognitively adapt to varying styles. It also allows for easier and more comprehensive text-based searching, since all items being searched for will have identical spacing.

Installing Checkstyle

When downloading Checkstyle for use in jGRASP, it is best to get the -bin.zip or -bin.tar.gz version. These will unpack into a directory named "checkstyle-" followed by the version number. jGRASP will automatically find this if it in a common tool location. If you get only the Checkstyle -all.jar file instead, just put it in a directory with a name that starts with "checkstyle" in a common tool location and jGRASP will find it.

After unpacking Checkstyle or putting the Checkstyle jar file in an appropriate directory, shut down and restart jGRASP and it should be automatically recognized. When a Java source code file is in focus, you should see various "Check..." functions under Tools > Checkstyle, as well as icons at the right of the tool bar. If Checkstyle is not automatically recognized, you can use Tools > Checkstyle > Configure to specify the location.

Configuring the Checkstyle Plugin

Use Tools > Checkstyle > Configure to change the Checkstyle plugin settings. The most important setting is the choice of checks file. This is an XML file that specifies the style and design checks that will be enforced. jGRASP is delivered with several checks that are compatible with CSD-formatted code (three space indent), and these will be available in the "Checks File" dropdown list. Note that for older versions of Checkstyle some names include a version number or version number range. Checkstyle does not maintain backward compatibility of checks files, so you must choose a checks file that matches the checkstyle version number (or a numberless one if you have a recent version of Checkstyle).

Running Checkstyle

Use Tools > Checkstyle > Check File or the Checkstyle file toolbar icon to run Checkstyle on the current source file. Tools > Checkstyle > Check Directory or the Checkstyle directory toolbar icon will run Checkstyle on all Java files in the same directory as the current source file. If the current file is in a project, Tools > Checkstyle > Check Project Files or the Checkstyle directory icon on the "Open Projects" toolbar will run Checkstyle on all project files.

Checkstyle errors will appear in the "Compile Messages" window. You can click on these to go directly to each error. If you are fixing multiple errors, you can turn on line numbers for the file, then use "freeze line numbers" so that clicking will still take you to the correct locations after lines have been added to or removed from the file. Don't forget to turn off "freeze line numbers" afterward.

If you are using a project, the most recent Checkstyle result will be shown next to each source file in the "Open Projects" window of the "Browse" tab. An orange square indicates that the file has not been checked since the last edit, a red X that the last check had one or more errors, and a green check that the last check had no errors.

---

DCD

DCD is a tool for finding unused or potentially unused code in Java source files.

Installing DCD

Download the DCD zipped project or just the jar file, and put it in a directory with a name that starts with "dcd" in a common tool location. Shut down and restart jGRASP. When a Java source code file is in focus, you should see a "Find Dead Code..." function under Tools > DCD, as well as an icon at the right of the tool bar. If DCD is not automatically recognized, you can use Tools > DCD > Configure to specify the location.

Running DCD

Use Tools > DCD > Find Dead Code in Project Directories to look for dead code in all project directories. If the current file is not in a project, the available function will be Find Dead Code in Current Directory. You can also use the DCD toolbar icon to invoke these functions.

DCD results will appear in the "Compile Messages" window. You can click on the dead code message lines to go to the class containing the potentially unused methods, fields, and variables.

---

Findbugs

FindBugs is a tool that identifies potential bugs in Java source code.

Installing FindBugs

Download one of the compressed FindBugs files. These will unpack into a directory named "findbugs-" followed by the version number. jGRASP will automatically find this if it in a common tool location. Shut down and restart jGRASP. When a Java source code file is in focus, you should see a "Find Bugs in ..." function under Tools > Findbugs. If FindBugs is not automatically recognized, you can use Tools > FindBugs > Configure to specify the location.

Running FindBugs

Use Tools > FindBugs > Find Bugs in Project Files to look for bugs in all project files. If the current file is not in a project, the available function will be "Find Bugs in File". You can also use the FindBugs toolbar icon in the "Open Projects" window of the "Browse" tab for project files or on the main toolbar for non-project files to invoke these functions.

FindBugs results will appear in the "Compile Messages" window. You can click on each potential error message to go to its location.

Note that the FindBugs plugin may fail for a large number of files, due to command line length limitations. If you have a project with a large number of files, you should run FindBugs directly and create a FindBugs project corresponding to your project.

---

JUnit

JUnit is a unit testing framework for Java.

Installing JUnit

jGRASP will automatically find JUnit if it in a directory with a name starting with "junit" within a common tool location. You should create such a directory, then download the junit and hamcrest jar files and save them there.

After putting the junit and hamcrest files in an appropriate directory, shut down and restart jGRASP and JUnit should be automatically recognized. When a Java source code file is in focus, you should see a "Create Test File" function under Tools > JUnit, as well as an icon at the right of the tool bar. If JUnit is not automatically recognized, you can use Tools > JUnit > Configure to specify the location.

Creating a Test File

With a source file in focus, use Tools > JUnit > Create Test File or the JUnit create test file toolbar icon to create a corresponding test file. After the test file has been created, the menu option and toolbar button become Edit Test File.

Test cases are added to the test file in form of test methods. Note that the defaultTest() method provided by jGRASP asserts that 0 equals 1, so that the test will fail. This test method should be replaced by your own relevant test methods. See the JUnit tutorial for details of creating, compiling and running test methods.

If a test file for a project is not created using the steps above (the file was created outside of jGRASP, or it was created as a regular source file), it must be marked as a test file. When adding the file to a project, if the JUnit annotations are present it should automatically be recognized and added to "Test Files" rather than "Source Files". If a test file is in the "Source Files" category for a jGRASP project, right-click on the file and select "Mark as Test", and the file will move to the Test Files category. When both categories are present, you can also drag files from one category to another.

Running JUnit

Use Tools > JUnit > Compile and Run Project Tests or the JUnit run toolbar icon to compile (if necessary) and run all the tests associated with the project of the current source file. If the current source file is not in a project, use the toolbar icon or the "Compile and Run Tests" menu item. You can also use the compile toolbar icon to compile all test files for the current project or file without running the tests, and various menu items under Tools > JUnit to compile all test files, or compile or run individual test files.

To run JUnit tests in debug mode, use Tools > JUnit > Compile and Debug Tests or Debug Tests.

When JUnit tests are run, a dialog will appear showing the test files, tests, and status of each test. You can click on a failure message in the dialog to go to its location. Errors also appear in the "Run I/O" window and you can click on them there.

If you are using a project, the most recent JUnit result will be shown next to each source file in the "Open Projects" window of the "Browse" tab. A red-white-green square indicates that the test file has not been run (for test files) or that the test file associated with the source file (for source files) has not been run since that last time the source or test file was edited or compiled. A red X on the icon indicates that the last test had one or more failures, and a green check that the last test had no failures.

---

Web-CAT

Web-CAT is an automatic grading system for software projects. If you are a student in a course that uses Web-CAT for grading, you can use the plugin to submit projects directly from jGRASP.

Configuring the Web-CAT Plugin

Use Tools > Web-CAT > Configure to specify the assignment definition URL. jGRASP uses the same URL as the Web-CAT plugin for Eclipse, and this typically ends with "/eclipse". Your instructor will supply this URL.

Submitting a Project to Web-CAT

Use Tools > Web-CAT > Submit Project Files or the Web-CAT icon in the "Open Projects" window of the "Browse" tab to submit a project. A dialog will allow you to choose the course and project files to be submitted, and then to enter your user name and password to submit the files.

Submission results will appear in a browser window, using the default browser for your system.