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.
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.
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).
Save Current Workspace - saves all the current workspace
settings: the desktop, open projects, and workspace settings. This
happens at exit or when changing workspaces anyway, so this is provided
only for protection against a crash.
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.
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 or a new Java project
with subdirectories.
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.
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.
Desktop - settings that deal with the appearance and
functionality of the desktop.
Virtual Desktop - turns the virtual
desktop on and off. If it is off, all CSD windows, UML windows,
CPG windows, and canvas windows will be top-level windows. If it is on,
these windows can be moved in and out of the virtual desktop(s)
individually (Escape Desktop or
Enter Desktop is under the
File menu on each of these windows). When
the desktop is turned on, all windows are moved onto the desktop,
regardless of their states at the time it was turned off.
Full-Height Tab Pane - if checked, the
tab pane on the left side of the Control Panel will extend to the
bottom of the Control Panel when virtual desktop mode is on. This
gives more height to the debug window, etc, and less width to the
messages. You can also use the leftmost icon on the control panel
message bar to switch between these modes.
Open Desktop Windows Maximized - if on, any window
opened in the virtual desktop(s) will be initially maximized. This means the virtual desktop
will behave like a tab pane. You can
also use the rightmost icon on the control panel message bar to toggle
this feature.
Show Close Buttons on Window Bar -
if on, a window bar button with mouse focus will have a close button
that can be used to close the associated window.
Focus Follows Mouse - when on, you can set keyboard focus
to CSD windows and most other text-entry windows in the virtual desktop(s)
by moving the mouse over them. Unfortunately, using the mouse in a CSD
window on the virtual desktop(s) will still raise it to the top, but you
can type and use keyboard accelerators in a non-top-level window.
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:
Show Documentation Outside jGRASP -
if on, display of javadoc documentation for the Java API and
user classes will be in the default system browser (Netscape
on systems that don't have a default browser). On Windows,
link targets within a local html file will not be followed in
that case.
Java API Documentation Root - specifies the URL
at which to search for Java API documentation. The path should
end at the "api" directory.
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
Workspace - opens a CSD
settings dialog for the current workspace, and selects the
CSD tab, which has settings that change
CSD generation and editing properties.
Project - opens a CSD
settings dialog for a project, and selects the
CSD tab, which has settings that change
CSD generation and editing properties.
File - opens a CSD
settings dialog for the active file, and selects the
CSD tab, which has settings that change
CSD generation and editing properties.
Auto Generate CSD - if on, a CSD is generated at load time,
before compiling, etc. This setting applies to all CSD windows.
CSD Window Popup Menu Enabled - when on, there will be a
popup editing menu for CSD windows. The particular mouse event that
triggers the popup is determined by the JVM and Look-And-Feel. On
Windows and Linux JVMs, the event is generally any right
mouse click. Turning this off allows you to use the CSD window right
click function that selects tokens with one click, and levels of
enclosing braces with more clicks (CTRL-left_click does the same thing).
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.
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 settingsCSD 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
Plain Text - match the search text. A search will
begin at the end of the previous match.
Regular Expression - match a regular expression.
A search will begin at the end of the previous match.
If the pattern contains no groups, the whole match will be reported.
Otherwise, there will be a match for each matching group. For example,
the pattern t(e)s(t) will result in two
matches for "test", one for the "e" and one for the second "t".
Zero-length groups are allowed, but the selection will be one character
long. For example, t(\S*)est will select
the "e" in "test". See
the
Java Pattern API for a description of the pattern format.
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:
local file: -link
"file:///C:/Users/Me/Documents/downloaded_docs/docs/api"
Oracle website: -link
"https://docs.oracle.com/en/java/javase/18/docs/api"
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.
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:
Reachability - the number of conditions that must be
evaluated to reach the segment from outside of the enclosing method,
function, or other top-level statement block. This is the traditional
definition of reachability.
Content - the log of the number of significant tokens in
the segment. Some punctuation, such as block-enclosing braces or a
statement-ending semicolon, is not considered significant. A pair of
parentheses is counted as one token.
Breadth - the number of statements, methods, etc. in the
innermost block containing the segment.
Inherent - value assigned based on the inherent
complexity of the innermost enclosing structure. For example, segments
in switch or case statements are assigned an inherent complexity of
3.0. This reflects the view that some structure types are inherently
more complex than others.
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.
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).
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
Native Print - allows you to print using the native
system. This is typically much faster than JVM printing. For UNIX/Linux,
the native print is just a PostScript print using the command set in the
workspace print settings. The font
setting is ignored in this case, and Courier font is used.
Print to File (PostScript) - prints to a PostScript file.
The font setting is ignored and a Courier font is used.
Print to File (RTF) - prints to a Rich Text file. For now,
no formatting is done. The only print settings that are used are font,
font size, and color.
Print PostScript - prints to a PostScript printer through
Java.
JVM Print - prints using generic (not PostScript specific)
Java printing. This tends to be very slow, and produces very large
print files.
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.
Generate CPG - generates a CPG for the current file.
Find CPG Window - pops up the CPG window associated
with the current file.
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.
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
Convert Whitespace to Tabs - converts spaces to tabs where
appropriate in the selected text or all text if there is no selection, in whitespace, comments, and preprocessor
directives. Note that this could change the semantics of preprocessor directives if spaces are used within
preprocessor tokens. Relative indentation will be preserved if the current font is fixed-width, otherwise it may
not be.
Convert All Whitepace Tabs to Spaces - converts tabs to spaces in
the selected text or all text if there is no selection, in whitespace, comments, and preprocessor directives.
Note that this could change the semantics of preprocessor directives if tabs are used within preprocessor
tokens. Relative indentation will be preserved if the current font is fixed-width, otherwise it may not be.
Convert Indentation to Tabs - converts spaces in indentation to
tabs where appropriate in the selected text or all text if there is no selection. Indentation includes continued
lines of multi-line comments and preprocessor directives. Note that this could change the semantics of
multi-line preprocessor directives if spaces are used within preprocessor tokens. Relative indentation will be
preserved if the current font is fixed-width, otherwise it may not be.
Convert All Indentation to Spaces - converts tabs in indentation to
spaces in the selected text, or all text if there is no selection. Indentation includes continued lines of
multi-line comments and preprocessor directives. Note that this could change the semantics of multi-line
preprocessor directives if tabs are used within preprocessor tokens. Relative indentation will be preserved if
the current font is fixed-width, otherwise it may not be.
Strip Trailing Whitespace - strips spaces and tabs from
the ends of lines in the selected text, or all text if there
is no selection.
Reserved Words (languages with case-insensitive reserved
words only)
Convert to Upper Case - converts reserved
words to upper case, for all reserved words in the current
selection, or all text if there is no selection.
Convert to Lower Case - converts all reserved
words to lower case, for all reserved words in the current
selection, or all text if there is no selection.
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.
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.
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
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)
Create New Instance - allows creation of one of
the top-level classes defined in the file.
Invoke Static Method - allows invoking a static method
on one of the top-level classes defined in the file.
Create Array - allows creating an array
of one of the top-level classes defined in the file.
Create New Instance of Named Class - allows creation
of a Java library class, any class in with the same package root
as the current file, or any class in the current project.
Invoke Static Method on Named Class - allows invoking a
static method on a Java library class, any class in with the same
package root as the current file, or any class in the current project.
Create Array of Named Class - allows creating an
array of a primitive type, Java library class, any class in with
the same package root as the current file, or any class in the
current project.
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
Plain Text - match the search text.
A search will begin one character past the start of the previous match.
Regular Expression - match a regular expression. When on,
Find Backward is not available. This mode
is not available when Block Cut and Paste is on.
Zero-length matches are ignored. A search will begin at the end of the
previous match. If a search pattern contains no capturing groups, the
entire match will be selected. If it contains capturing groups, at least
one must be matched. The first match will be selected. For example,
t(e)s(t) will select the
"e" in "test". Zero-length groups are allowed. For
example, t(\S*)est will move the cursor
to the position before the "e" in "test" (it will select "nothing" before
the "e"). See the
Java Pattern API for a description of the pattern format.
Search
All Text - search for text-based matches anywhere in the
code.
Tokens and Comments - search for full tokens and comments.
For example, "test" will match only the identifier "test", not "test1"
or an occurrence of "test" in a string or comment, and "s =" will match
"s=" or "s =" but not "rs =" or "s /*comment*/ =".
Tokens - search for full tokens while ignoring comments.
For example, "test" will match only the identifier "test", not "test1"
or an occurrence of "test" in a string or comment, and "s =" will match
"s=", "s =", or "s /*comment*/ =", but not "s ==".
Tokens, Comments, WS - search for full tokens, comments,
and whitespace segments between tokens and comments. For example,
"test" will match only the identifier "test", not "test1"
or an occurrence of "test" in a string or comment, and "s =" will match
"s =" but not "s =", "rs =" or "s /*comment*/=".
Strings - search for text-based matches only within
strings.
Comments - search for text-based matches only within
comments.
Folds
Unfold - if on and the text is found in a folded area,
the minimum amount of unfolding that will reveal the text will be done.
Stop - if on and the text is found in a folded area, the
cursor will stop at the fold.
Skip - if on, folded areas will be skipped.
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.
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
Shift Key Down - same as middle mouse button.
Ctrl Key Down - same as right mouse button with CSD Window
popup disabled (see below). If at left of window, left button click
toggles a bookmark or breakpoint.
Alt Key Down - if at left of window, left button click
toggles a bookmark.
Single Click - positions the cursor. If at left of window,
selects a line, toggles a breakpoint.
Double Click - if on text, selects a whitespace-delimited
word or whitespace. If on CSD, folds the CSD structure
recursively. If at the top of a structure that is folded, unfolds
recursively. If on a folded CSD line, unfolds that line.
Triple Click - selects a line.
Quadruple Click - selects the whole text.
Middle Mouse Button - Extends the current selection.
Right Mouse Button - if CSD Window popup is enabled, brings
up the popup menu, otherwise:
Single Click - selects a single language-specific token or
whitespace block.
More Clicks - selects layers of matching parenthesis and
braces.
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:
Fold (Shift-F3) - If multiple lines of text are
selected, the first to last lines of the selection become a single fold.
Otherwise, the CSD structure containing the cursor is folded. If the
cursor is at the top line of a multi-part structure, such as a switch
statement or if-else statement, each part of that statement is folded.
Fold Recursive (F3) - If multiple lines of text are
selected, any CSD structures within the selection are folded
recursively. If there are no CSD structures in the selection, nothing is
folded. Structures partially within the selection are partially folded.
If no text or part of one line of text is selected, the CSD structure
containing the cursor is folded recursively. If the cursor is at the top
of a multi-part structure, such as a switch statement or if-else
statement, each part of that statement is folded recursively.
Fold All Recursive (Ctrl-F3) - Does the same thing as
selecting all text then folding recursively.
Unfold (F4) - unfolds the next fold following the cursor
position.
Unfold Recursive (Shift F4) - unfolds the next fold
following the cursor position, and any folds within that fold.
Unfold All (Ctrl-F4) - removes all folds.
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.
To use the integrated debugger, jGRASP must be running under
the JDK (not a JRE). 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.
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 "machine instruction size steps" is selected, approximately
one machine or 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
name - name given to the thread. You may want to name
any threads you start, to make them easier to track.
[state] - shows the current suspend state: running, waiting,
waiting on monitor, sleeping, not started, zombie, or unknown. Due to
bugs in older versions of Java, this value may be incorrect.
(debugger action/state) - shows what the debugger is
currently doing with respect to the thread: at breakpoint, suspended,
running to cursor, or stepping. If none of these are true (the thread is
running normally), nothing is shown.
monitors - shows the monitors owned by the thread, by
id number. This is the same id number shown for objects in the variables
window. If the thread is waiting on a monitor, this monitor is shown in
[braces].
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 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.
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:
No generics.
No assignment expressions (= += etc.).
No anonymous class creation.
No increment or decrement (++ --).
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:
orange - supertype
green - same type
yellow - subtype
cyan - implemented interface
light cyan - interface implemented by subclass
magenta - implementing class
light gray - non-implementing class or unrelated
interface
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 cast.
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.
Bugs in Version 2.0.6_10 Beta 2 Fixed in Version 2.0.6_10 Beta 3
Inner class creation using qualified NEW does not work.
Bugs in Version 2.0.6_10 Beta Fixed in Version 2.0.6_10 Beta 2
For many versions of Java, keyboard navigation does not work in
dialogs.
For the Meta Dark themes, the highlight border and selected menu
item background are not visible.
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 windowcontext 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 windowcontext 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.
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:/Users/Me/Documents/downloaded_docs/docs/api"
Oracle website: -link "https://docs.oracle.com/en/java/javase/18/docs/api"
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.
Note that this is not linked when generating user documentation, it
is only used by jGRASP when displaying documentation from the
Java UML diagram and Workbench.
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).
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.
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_17 Beta. Check
https://www.jgrasp.org for the latest version of
jGRASP.
jGRASP is written in Java. "Bundled" jGRASP distributions include Java. For non-bundled release, Java
11 or higher must be installed on your machine in order to run jGRASP.
The "bundled" jGRASP distributions include a Java compiler. non-bundled distributions do not, and no
compilers for other languages are included in the bundled versions.
Which JVM to Use
For non-bundled jGRASP, the latest Oracle JDK or OpenJDK from a well-known source is suggested. If you
are using a very new version of Java or one from a vendor we don't recognize, you may get a warning at startup.
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 panelsettings 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:
multiClickTime: 500
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:
xrdb -merge $HOME/.Xdefaults
(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
The "bundled" jGRASP distributions include Java. If you install a non-bundled version, Java 11 or
higher is required. You can get the latest Java 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:
1) get from previously set jGRASP startup settings.
2) get from "-a" command line parameter if present
3) get from JGRASP_JAVA environment variable if present
4) search registry entries for known vendors, preferring JDKs over JREs
5) check the PATH for javac.exe - if found look for
java.exe in the same place (avoids finding JRE before JDK)
6) check the PATH for java.exe.
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:
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:
cd /Applications/jGRASP.app/Contents/Resources/jgrasp
java -jar jgrasp.jar
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
In order to use the integrated Java debugger, jGRASP must be running under a JDK (not a JRE).
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.
-h - display a help message.
-nosplash - do not show the splash screen at startup.
-l line_number - select line_number for the filename
argument.
-g language - force a language for the
filename argument. language can be C, +, J, A, V, O, P for C, C++, Java,
Ada, VHDL, Objective-C, and Python.
-d directory - alternate settings
directory. See "Command line arguments for jGRASP itself" below.
-a JGRASP_JAVA - specify the java command
used to start jGRASP. This can also be set in a JGRASP_JAVA environment
variable and through jGRASP startup settings on Windows and macOS.
If not specified, "java" will be called on UNIX/Linux, and on
Windows the registry and PATH will be searched for "java.exe" as
explained in Running on Windows.
-j JGRASP_HOME - specify the root of the
jGRASP installation. This can also be set in a JGRASP_HOME environment
variable. The "jgrasp" shell script attempts to "locate itself", so this
should not be necessary under normal circumstances. This should never be
necessary on Windows.
-cp JGRASP_CLASSPATH - specify a
classpath to be used for jGRASP. This can also be set in a
JGRASP_CLASSPATH environment variable. The "jgrasp.jar" file will always
be prepended to this path. Under normal circumstances using this
argument should not be necessary.
-Jjvm_arg - pass jvm_arg to the JVM running
jGRASP. For example, -J-Xmx2048m will make
the maximum size of the memory allocation pool for jGRASP 2 Gigs.
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.
-d directory - use directory as the settings directory
instead of USER_HOME/.grasp_settings. directory must be a full path
name. By using this, you can run two jGRASP sessions concurrently and
they will not interfere with each other, or you can keep
two set of setting on the same system and user account.
-h - print a help message.
-v - print the version number.
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.
Control Panel - the top level jGRASP window.
CSD Window - the source code editing windows. Also
referred to as "editing window".
Virtual Desktop or Desktop - a desktop window
that may contain code editing windows, CPG windows, etc.
Tab Page or Page - one page of a tabbed window.
Menu Accelerator - a function key or control-key
combination that performs the same function as a menu item.
Context Menu - a menu that pops-up over a specific
interface item. In most environments, a right mouse click over
the item triggers such a menu.
Swing - also called JFC, the Java gui class library
that jGRASP uses.
Compiler Environment - a group of settings that specify
how jGRASP will interface with a particular compiler.
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
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 Java. Many of them apply only to old versions of Java.
File chooser details view does not resize rows when the font size is changed under some Java version
(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
The current focus is the jGRASP Plugin for IntelliJ, which
brings the jGRASP viewers and canvas to IntelliJ IDEA and Android Studio,
for Java and Kotlin.
Future
Code completion for Java.
More flexible compiler environments.
Ability to run multiple commands for one "compile" or "run" item,
add items to menus other than "Compile" and "Run", specify icons
and have items appear on the toolbar.
Forward development features for the UML
diagram (drawing, creating shell classes).
More features for the integrated Java debugger: hex and
octal display for values and array indices; a dynamically updated
monitor display window, listing owning thread and waiting threads by
monitor; automatic deadlock detection; byte code display; display of
current watchpoints to make removing them easier; ability to set
breakpoints without access to source code; repeated, counted
stepping (eg: step in 42 steps); ability to disable/enable garbage
collection for objects; assistance for memory leak (lost reference)
detection; exception breakpoints; listing of all loaded classes with
their fields and methods; show classpath, version, and other
information for target VM; tracing variable changes; dumping of
thread, stack, and variables to message window for easy cut-and-paste.
A debugger connection and interface for languages other
than Java.
Command line functionality for batch formatting and
printing.
Have a project realize that it has been moved, and
copy previous file settings.
Add an editor for user defined templates.
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_17 Beta.
Built on March 25, 2024.
Copyright 1999-2024 Auburn University
Website:
https://www.jgrasp.org
Project Director:
James H. Cross II, Ph.D.
Computer Science and Software Engineering
3101 Shelby Center
Auburn University, Alabama 36849-5347
graspATengDOTauburnDOTedu
Chief Software Engineer:
Larry A. Barowski, Ph.D.
Empirical Evaluation:
Dean Hendrix, Ph.D.
Cyber Research:
David Umphress, Ph.D.
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):
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 SoftwareBundled 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:
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.
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_17 Beta copyright 1999-2024 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 (crossjhATauburnDOTedu). Permission to
distribute jGRASP for educational purposes covers all media
finalized prior to December 31, 2025 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, crossjhATauburnDOTedu).
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.
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.
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.
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.
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.
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), 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).
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.
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.
%<ENV_name> [new] - the system environment variable "name", for
example %<ENV_USERPROFILE> for the USERPROFILE environment variable. The variable must exist, or an error will
occur when any command that uses the variable is executed.
%<REG_path> [new] - the Windows registry value at "path", for
example %<REG_HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\Desktop> . The
item must exist and must be a string value, or an error will occur when any command that uses the variable is
executed.
%<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.
%<UCBASE> - 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.
%<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> - Java 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 Java 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 for
file-level commands, path to the directory containing the project for project-level commands.
%<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.
%<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.
%<TTY> [new] - true if I/O
streams should be marked as TTYs on Windows regardless of the user
setting.
%<NOTTY> [new] - true if I/O
streams should not be marked as TTYs on Windows regardless of the user
setting.
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.
Any variable may be prepended by UC_ . In that case, the first character
of the result, if any, will be converted to upper case.
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.
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.
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, Compile and Link, Compile, Check, Run, and Debug 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:
f = filename
c = class
u = unqualified file name (used in combination with class)
m = method name (used in combination with class and byte code
offset)
b = byte code offset (used in combination with class and method
name)
1 = start line
2 = start column
3 = end line
4 = end column
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 panelTools
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.
Environment allows environment
variables to be changed and special jGRASP variables to be set. Variables
are set one-per-line, using the following format:
Replace: VAR=VALUE
Prepend: VAR+=VALUE
Append: VAR=+VALUE
Set Special: SPECIAL_VAR==VALUE
For now, the only special variables are NOT_FOUND_MESSAGE, which specifies the message to display when
the compiler is not found, and ADD_EXE_PATH, which add the directory containing the executable to the path for
Windows only.
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. 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.
-Run -Debug
PATH+=C:\mypath;
Compile
DEBUG_TEST=1
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:
x //* this is x divided by 3 in ANSI C
*/ 3 .
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.
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.
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
Tree Down - lays out selected objects, dependents of
selected objects, or all objects in a vertically oriented tree.
Only inheritance links are considered.
Tree Right - lays out selected objects, dependents of
selected objects, or all objects in a horizontally oriented tree.
Only inheritance links are considered.
Spring - lays out selected objects or all objects
using a spring embedding layout algorithm. All links are considered.
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 will be searched for in the Java
classes. If the project contains more than one main(), 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
Create New Instance of Class - allows you to create a
new instance of an arbitrary class.
Invoke Static Method - allows you to invoke a static
method on an arbitrary class.
Create Array - allows you to create an array of
arbitrary type.
Run Topmost - if on, then the any gui started
by using workbench actions 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.
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.
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.
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 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.
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.
to run Checkstyle on the current source file.
will run Checkstyle on all Java files in the same directory as the current
source file. If the current file is in a project,
to create a corresponding test file. After the test file has been created,
the menu option and toolbar button become 
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
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.