CSD Window

"CSD window" is the name given to source code editing 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 not considered a modification, because even though it may change the text it will not change the code structure.

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, but it may be floated or moved to the bottom (or the sides, which is not very useful). All CSD window tool bars may also be removed 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, but it may be floated or moved to the top (or the sides, which is not very useful). All message bars may be removed using the "View" menu.

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


 
 

File Menu

Clear - closes the currently open file and clears the text.

Open - brings up an open file dialog.

Save - saves the current file. By default it is saved with the same line terminator format (binary, DOS, or Mac.) as it had when loaded. If the format could not be determined when loaded (because there was more than one type of line terminator), it will be saved in binary mode.

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

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

Add to Project - if the file is not in the current project, add it to the current project with either a relative or absolute path. Relative paths are relative to the project file location, and are platform independent. They can not be used for the default project (you must name the project using, for example, "Project" / "Active Project" / "Save As").

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.

CPG- 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.

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.

Print

Native Print - allows the user 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.

JVM Print - prints using Java. This tends to be very slow, and produces very large print files.

Print Settings - opens a print settings dialog for this file, or workspace or project level print settings, and selects the "CSD" tab.

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

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

Exit This Window - closes the CSD window.


 
 

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.

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.

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

Spaces/Tabs

Tabify - converts spaces to tabs in the selected text, or all text if there is no selection.

Untabify - converts tabs to spaces in the selected text, or all text if there is no selection.

Strip Trailing Whitespace - strips spaces and tabs from the ends of lines in the selected text, or all text if there is no selection.

Find/Replace - brings up the find dialog.

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

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

Select All - selects all text in the window.

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.

CSD Window Settings - opens a CSD settings dialog for this file, or workspace or project level settings, and selects the "CSD" tab.

Compiler Settings - opens a CSD settings dialog for this file, or workspace or project level settings, and selects the "Languages" tab.


 
 

View Menu

Generate CSD - generates a CSD.

Remove CSD - removes the CSD.

Auto Generate CSD - if on, a CSD is generated at load time, after a template is inserted, etc. This setting applies to all CSD windows.

CSD Context Hints - if on, show CSD context hints in CSD Windows.

Fold - see folding.

Marks - see marks.

Bookmark - see bookmarks.

Breakpoints - see breakpoints.

Split View - allows the user to select from a single view CSD window, or a vertically or horizontally split dual view.

Tool Bar - if off, the tool bar is not shown in all CSD windows.

Tool Bar Buttons - allows the tool bar buttons to be shown as icons, text, or both, in all CSD windows.

Message Bar - if off, the message bar is not shown in all CSD windows.

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.


 
 

Templates Menu

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.

The user may define templates in the  template  directory of the  .grasp_settings  directory in the users home directory (typically  C:\Windows  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.


 
 

Compiler Menu

This menu provides compiler functions set up in the CSD window settings dialog. Output appears in the message window, which also provides a button to stop the compile process. Due to Java bugs, on some systems the end of the compile process may not be recognized every time, and the user will have to use this button to return jGRASP to the non-compiling state.

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).

Compiler Settings - opens a CSD settings dialog for this file, or workspace or project level settings, and selects the "Compiler" tab.

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

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.

Actions that would conflict with compiling, such as saving the file or activating another compile process, are blocked during compiling.


 
 

Run Menu

This menu provides run functions set up in the CSD window settings dialog. Input and output are provided by the message window, which also contains a button to kill the running process.

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 MSDOS Window" checkbox (Windows only) is on, the "Run", "Run as Applet", and "Debug" will use a DOS shell for I/O. The user will be prompted in the DOS shell to hit a key to start the process and to continue after the process is finished. In Windows NT, you can right click on the title bar and change the window properties, including width and height, before starting. In Windows 95/98 you can change the properties of the conagent.exe file (standard location is C:\Windows\System\conagent.exe) to change the default number of screen lines for DOS shells. In Windows NT, you can do the same thing using cmd.exe (standard location C:\Windows\System32\cmd.exe).

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.

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.

During a run, actions that would cause a conflict, such as activating another run or a compile process, are blocked.


 
 

Find Dialog / Page

This is the dialog or page for find and replace in CSD windows. All CSD windows in the 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.

Replace With - the replacement text.

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.

Awk/Grep Reg. Exp - match extended awk/grep style 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.

Perl5 Reg. Exp. - match a Perl 5 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 groups, the entire match will be selected. If it contains 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 perlre man page for a description of the pattern format.

Search

All Text - search all of the text.

Tokens Only - search only for full tokens. For example, "test" will match only the identifier "test", not "test1" or an occurrence of "test" in a string or comment, and "12" will match the number "12", but not "127".

Strings - search only within strings.

Comments - search only within comments.


Folds

Skip - if on, folded areas will be skipped.

Stop - if on and the text is found in a folded area, the cursor will stop at the fold.

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.


Find - searches forward in the text.

Find Backward - searches backward in the text.

Replace - replaces the current selection with the replacement text.

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

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

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

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

Clear All Marks - removes all marks.


 
 

Open File Dialog

A dialog for opening files.

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

You can also type a list of extensions into the "Filter Extensions" field to filter by extensions. These must be separated by whitespace, and can start with ".", "*.", or nothing. For example: "*.c *.cpp", ".c .cpp", and "c cpp" will all show only files that end in ".c" or ".cpp". This feature is provided for users running under JDK 1.3. Under 1.4, 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).

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. If at left of window, left button click toggles a bookmark.

Alt Key Down - if at left of window, left button click toggles a breakpoint.

Single Click - positions cursor. If at left of window, selects a line, toggles a bookmark, or toggles a breakpoint depending on the position.

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 which 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.


 
 

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. For a mouse click, the click must be on the folded line.

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 CTRL key down, or without the CTRL key down if in the bookmark area of the border, 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.

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 with the ALT key down, or without the ALT key down if in the breakpoint area of the border, will toggle a breakpoint.


 
 

CSD Context Hints

With this feature turned on and a CSD generated, the top or bottom of any structure which 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.

For nested or multi-stage structures, such as nested if/else or switch/case, the top 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 line of the entire structure.

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


 
 

CSD Pair Hints

Holding down the control key and moving the mouse over a brace, bracket, or parenthesis will highlight that character and the matching brace, bracket, or parenthesis.


 
 

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.


 
 

Extended Awk Regular Expressions

From the ORO documentation:

This is the traditional Awk syntax that is supported:

This is the extended syntax that is supported: