Java SuperCollider for Eclipse

Using Eclipse

Before starting to work with JSC you might want to check out the integrated help from Eclipse. A lot of these topics are also true for JSC.

Some Eclipse topics/features you might want to have a look at:

• Eclipse Basic tutorial
• Concepts
• Working with views and editors
• Working with projects, folders and files
• Importing
• Navigating and finding resources
• Comparing resources
• Working with local history
• Problems, bookmarks, tasks and other markers
• Team CVS tutorial (there is also a Subversion plugin for Eclipse called Subclipse)

Starting JSC and configuration

After starting Eclipse choose 'Window/Open Perspective/other...' from the menu and select the SuperCollider perspective. When JSC gets started the first time the configuration wizard is opened. You need to set the SuperCollider3 directory on the first page of the wizard. On the second page you need to set the support directories for SuperCollider to directories of your choice. You can choose to create these directories as projects in your workspace but this feature is not yet tested and you might run into problems. 

JSC makes changes to your SuperCollider system extensions directory. When a project gets compiled the source folders of that project get copied into the system extensions directory into a sub-folder called JSCExtensions. You should not make any changes to this folder while working with JSC. After a project was compiled JSC will automatically keep track of changes in the project source folders.

Creating Projects

To create a new JSC project in the workspace you can use the JSC Project Wizard. Choose 'File/New/Other...' from the menu and then select 'SuperCollider/Project'. You can optionally add a 'src' folder to the project. This folder will get compiled with the SCClassLibrary once you compile the project. You can add additional source folders in the project settings - right click on the project and select 'Properties/SC Paths and Files'. Here you can also add files that will automatically get interpreted once you run the project. You can also add 'project references' to the project. When compiling a project all source folders from referenced projects will get compiled too.

Creating Files

You can use the JSC Source File Wizard to create new files in the project.

Opening the SuperCollider Editor

The editor gets opened automatically once you open a file with one of these endings: 'sc', 'scd'. You can change the file extensions that will be accepted as interpreter files in the plugin preferences.

Attention - Using JSC without SuperCollider?!

Because of license restrictions in the GNU General Public License (version 2) that prohibit linking a GPL covered software to an EPL (Eclipse Public License) covered software it is currently not possible to control SuperCollider from within JSC. The library jsclang.jar that would normally link to the SuperCollider language is not doing anything at the moment.

A lot of the features described below will not be working in the normal JSC release version until these issues are resolved. 

If you are interested in licensing stuff  have a look here:

Frequently Asked Questions about the GNU Licenses

An Analysis of the Eclipse Public License (version 1.0) and GNU General Public License (version 2.0) and the Interaction of Works Licensed Thereunder

Compiling the SCClassLibrary and using the interpreter

 You can use these actions from the SuperCollider menu:

• Compile Library - compiles the SCClassLibrary.
• Compile Project - compiles the SCClassLibrary and the source folders of the currently selected project.
• Interpret - interprets the currently selected text after the library has been compiled
• Stop - stops the interpreter
• Boot Default Server
• Stop Server
• Start SwingOSC
• Stop SwingOSC
• Run Main -  interprets all global interpreter files (see JSC preferences) and calls Main.run() afterwards.
• Run Project - Compiles the project if it isn't already compiled, interprets all global and project interpreter files and calls Main.run() afterwards.

Using the SuperCollider Editor

• press 'strg+space' for code completion. Code completion works for class names, keywords and for predefined code templates (try typing 'if' and then 'strg+space'). Code templates can be defined in the JSC preferences.
• Typing a period after a class name will show a list of it's class methods. Typing a period after a global variable will show a list of it's instance methods. Typing a period after a method where the return type is known will also show a list of  the instance methods for the return type. You can add methods with pre defined return types in the JSC preferences. You can also specify prefixes for methods that will certainly return the class name after that prefix. The default prefixes are 'as' and 'to'. So if you type 'asString' JSC will assume that the return type will be 'String'. Also all 'is', 'can', 'includes' and 'contains' methods will be assumed to return the type Boolean.
• Hovering over a class will reveal a text hover that shows the help to that class. Hovering over methods will show the implementations of that method and the references to that method. Hovering over a global variable will show a dump of the object this variable points to.
• Selecting a word will automatically search the file for this word and annotate the occurrences. You can change this behaviour in the Eclipse preferences (General/Editors/Text Editors/Annotations/JSCOccurrences).
• 'strg'-clicking on a class will open the implementation of the class. 'strg'-clicking on a method will start a search for implementations of the method.
• If you put the cursor next to a bracket its counterpart gets highlighted.
• If you double click after a bracket the text inside two bracket will get selected.
• Using the context menu you can:
  
  •  show the 'implementations of' / 'references to' classes and methods.
  •  shift code left or right.
  • comment/uncomment code
  • search the selected text in the workspace, file or project
• When right clicking on the left border of the editor you can
  
  • show/hide line numbers
  • add bookmarks to the document
  • add tasks to the document
• You can use the editor to open RTF files and HTML files but it is not possible to save these files. You can of course save the files with another extension using 'Save As...' if you did edit them and want to save your changes.

Using the console

• Clicking on file links in the console will take you to that file.
• You can interpret code from within the console and also use the menu actions 'Open help file', 'Implementations of' and 'References to'
• Some of the SC errors will be shown in red in the console output.

JSC Preferences

You can configure JSC with the JSC preference page - open the menu 'Window/Preferences' and then select 'SuperCollider'.

• SuperCollider/Editor - Preferences for the SuperCollider Editor.
  
  • Syntax - change the colours of the syntax highlighting
  • Content Assist - preferences like content assist delay and colours.
  • Return Values - here you can add return values to methods so they can be used with the content assist.
  • Templates - add templates for the code completion
• SuperCollider/SC Paths and Files - Here you can define SC source files that will get compiled with the SCClassLibrary and interpreter files that will automatically be interpreted when 'Run Main' is used.
• SuperCollider/SC Paths and Files/File Types - define the file extensions that JSC accepts as interpreter files.
• Some preferences for JSC can be set in other Eclipse preference pages:
  
  • General/Editors/Text Editors/Annotations/JSCOccurrences - preferences for the automatically annotated occurrences of selected words in the SC editor
  • General/Editors/Text Editors/Hyperlinking/SC Element - preferences for hyperlinks in the SC editor.
  • General/Appearance/colours and Fonts/JSC - change the font of text hovers
  • General//Keys - change the key bindings for commands

JSC Help View

• When you select 'TOC' you can switch between a browser style view and the Eclipse help.
• When the action 'Open Help File' is selected from the SuperCollider menu the help file to the currently selected topic (the selected text in the SC editor) is opened. This action will automatically search the SuperCollider/Help directory. This way you can use the help even if the plugin jsc.help is not up to date with the currently used SuperCollider3 version.
• You can interpret text and use the action 'Open Help File' from within the help view (only if your browser supports Javascript).
• You can use the help view as a web browser if you want. The button SC Home takes you to the SuperCollider homepage.
• 'Open in Editor' will open the help file in the SC editor (only working if you have opened a help file from the SuperCollider/Help directory).

Using the SC class JscEclipse and SwingOSC

You can find some JSC specific examples in the file 'jsc/examples/JSCEclipse_tests.scd'.