# SwingOSC -- version 0.61 RC SVN-176 (built 22-apr-09) --

### statement

| SwingOSC is an OpenSoundControl (OSC) server intended for scripting Java(tm), such as to create graphical user interfaces with AWT or Swing classes. It uses the reflection and beans mechanism to dynamically create instances of java classes and control them. A separate set of SuperCollider language classes is included to allow the building of GUIs from within sclang. SwingOSC is (C)opyright 2005–2009 by Hanns Holger Rutz. All rights reserved. SwingOSC is released under the GNU General Public License and comes with absolutely no warranties. To contact the author, send an email to `contact at sciss.de`

For project status, API and current version, visit www.sciss.de/swingOSC.

For OSC communication, SwingOSC uses the NetUtil library, which is licensed under the GNU Lesser General Public License (LGPL). The compiled library is included, for sourcecode and details visit www.sciss.de/netutil. SwingOSC also builds on top of ScissLib which is licensed under the GNU General Public License.

### security note

SwingOSC uses UDP and TCP network protocols. It allows to create and execute almost any kind of java code on your machine. Therefore, running SwingOSC in a network that can be accessed from outside is a severe security problem, allowing hijacking, information retrieval and massive damage on your machine. You have been warned!

It is strongly advised to launch SwingOSC with the -L option which limits communication to the local computer. Alternatively, make sure your firewall settings are appropriate.

### download

The current version can be downloaded here:

- sourceforge.net/projects/swingosc

The SuperCollider for Windows built maintained by the IEM Graz already comes with a preconfigured SwingOSC installation (however not always the newest):

- sourceforge.net/project/showfiles.php?group_id=54622&package_id=133499

Developers can download the lastest version from Subversion (SVN):

    > cd <baseDir>
    > svn co https://swingosc.svn.sourceforge.net/svnroot/swingosc/trunk/ SwingOSC

The subversion download comes in source form and needs to be compiled (see the compilation section below). The regular download already includes a precompiled binary.

### requirements / installation

SwingOSC is written in Java(tm) and requires a Java runtime environment (JRE) version 1.4 or better. On Mac OS X you already have this runtime. On other platforms you may need to download and install a recent runtime from java.sun.com. You can verify your current java version by opening a terminal and executing the command `java -version`.

Linux note: There are other free implementations for the Java standard platform, like Apache Harmony and GNU Classpath. However, most of them are not suitable for GUI applications since their AWT/Swing is incomplete or buggy. SwingOSC should work both with Sun's VM and OpenJDK. Note that you can have more than one java runtime installed (see nescivi's posting on this thread for details: www.nabble.com/swingOSC-installation-on-Linux-Ubuntu-7.04-t4638827.html).

- Installing SuperCollider classes : please refer to the separate file SuperCollider/readme.html
- Double-click launcher on Mac OS X : you can use the files `SwingOSC_TCP.command` and `SwingOSC_UDP.command` to boot a standard server. As of v0.29 they can be executed out-of-the-box. However, you may wish to customize the SwingOSC options using a text editor such as the `TextEdit` application. If you cannot double-click these files, select each in the Finder and open the information window (Cmd+I). Choose to open these documents with the `Terminal` application (located in `/Applications/Utilities`).

To use `MovieView.java` (i.e. `JSCMovieView`), you will need the Java Media Framework (JMF) classes from Sun (on Mac OS X use the cross-platform download). Put `jmf.jar` in your system's classpath, e.g. on Mac OS X that can be `/Library/Java/Extensions`. I'm hoping to find a better solution for movie playback in the future.

### launching the server

Open a terminal and `cd` into the SwingOSC folder. Either run the default script by typing `sh SwingOSC.sh`, or launch with custom options:

       > java [java-VM-options] -jar build/SwingOSC.jar [swing-osc-options]

where the VM options are:

- `-Dswing.defaultlaf=<LookAndFeelClassName>` : specify a custom look-and-feel class. e.g. `com.birosoft.liquid.LiquidLookAndFeel`.
- `-Dapple.awt.brushMetalLook=true` : (Mac OS only) use the brushed-metal window skin as known from the Finder and traditional SuperCollider GUI.
- `-Xdock:icon=application.icns` : (Mac OS only) use a prettier icon for display in the dock and programme switching screen.
- `-Xdock:name=SwingOSC` : (Mac OS only) alternative screen name

and the SwingOSC options are:

- `-t <port>` : use the given TCP port for message reception. The SuperCollider classes assume that you use port 57111!
- `-u <port>` : use the given UDP port for message reception. if absent, an arbitrary free port will be picked.
- `-L` : use loopback address ("127.0.0.1") for communication. if absent, the local host's IP address is used. when your computer is connected to a network and SwingOSC needs only be accessed from the local computer, make sure you use this option to minimize the security issue mentioned above.
- `-i` : run Swing initialization upon startup. On Mac OS, a terminal app becomes a GUI app with screen menu bar and icon in the Dock, as soon as an AWT or Swing component is created. This initialization can be enforced by using this opton.
- `-h <host:port>` : send a `[ /swing, "hello", <swingHost>, <swingPort>, <swingProtocol> ]` message to the given UDP socket. this kind of manual "bonjour" is used by the SuperCollider classes to detect the startup of the SwingOSC server.

if you wish to include custom java classes or libraries, you can either

- use the `/classes` OSC command (see OSC reference for details).
- or include them in the `SwingOSC.jar` file, add them to the java class path, as shown in the following example which adds the freetts speech libraries (assuming they have been copied to the `lib` folder):

         > java -cp build/SwingOSC.jar:lib/freetts.jar:lib/jsapi.jar de.sciss.swingosc.SwingOSC [swing-osc-options]

### documentation / usage

Please read the DevelopersNeeded note.

- A few example for SuperCollider and Pure Data are included in their respective `examples` folders.
- The file `OSC-Command-Reference.html` provides an introduction to the concept of SwingOSC and explains all commands that the server understands.
- API documentation is not yet generated. However some of the java classes contain already javadoc comments, so it should be quite easy to get started.

### compilation

The source code can be compiled using Eclipse SDK 3.4+ (www.eclipse.org) and Apache Ant 1.6.5+ (ant.apache.org). You need to install Ant-Contrib as well (first install Ant if you do not have it, then download Ant-Contrib and copy `ant-contrib.jar` into Ant's `lib` folder). The Eclipse project file is configured to run the regular Ant build file. You can make a clean build just with Ant from the terminal:

    > ant clean jar
    > ant test

The `"test"` will just launch SwingOSC so you can see if the build works; you can leave away that task. By default, NetUtil is included in the resulting file `build/SwingOSC.jar`. If wish to link externally to it, you can build like this:

    > ant -Dplain=true clean jar

To compile `MovieView.java`, you will need to have `jmf.jar` in your classpath (see requirements sections above). If JMF is not installed, the Ant build will skip the compilation of `MovieView.java` and you will not be able to use `JSCMovieView`.

### known issues

- in TCP mode SuperCollider on Mac OS X often crashes when the server quits.
- with a lot of messages sent en-bloc from sclang – and even a sparsely populated window setup means a lot of OSC traffic –, there can be a buffer overflow which results in the last messages being lost when using UDP transport. as a circumvention, you can either
  - use TCP mode
  - or put your GUI buidling process in a `Routine` and place short `wait` statements in the body until no more message dropping occurs.

### to-do list

- password protection in TCP mode?
- text file or similar with a restriction list of allowed classes to instantiate?
- add some nice stuff like tree view ...

### change history

#### v0.61 (apr 2009 - SVN rev. ??)

- Server: performance improvement, improved booting from SC
- SC classes: moved OSX specific stuff to separate folder, adding (still experimental) JSCMenuNode, JPen (joinStyle_, lineDash_, alpha_), adding JavaObjectD, SwingGUI (stringBounds), JSCTextView (open, linkAction), JSCContainerView (relativeOrigin), JSCWindow (initAction, toFrontAction, endFrontAction), JSCView (absoluteBounds), JSCUserView (relativeOrigin true), JSCPeakMeter added
- Refactoring: using ScissLib (application framework with window handler customization), now JCollider (for peakmeter, in future version for scope etc.)
- Bug fixes: 2037842, 2482337
- New features: 1849186

#### v0.60 (may 2008 - SVN rev. 77)

- sc classes: fixes for control rate scoping, JSCView (handleKeyUp/DownBubbling, focusColor_ dummy,), JPen (addArc, addWedge, addAnnularWedge, setSmoothing), JSCListView (bounds), JSCTextView (bounds, open), adding coarse String-bounds estimator,
- synced with new NetUtil and common classes version
- fixed loopback for -h rendezvous option (addresses problems on Linux and Windows Vista)
- Mac OS X tablet library now universal binary

#### v0.59 (feb 2008 - SVN rev. 56)

- sc classes: JavaObject (added double underscore syntax, calling prRemove from JSCPlug(Container)View), SwingOSC (separate java field, faster booting, bootSync fix), SwingOptions (javaOptions field), SwingGUI (updated), JSCMultiSlider (valueAction_ fix), JSCPopUpMenu (value_ fix), JSCListView (value_ fix), JKnob (was broken), removed JEZSlider, JEZNumber.
- java classes: DummyTransferHandler sends file-lists

#### v0.58 (jan 2008 - SVN rev. 47)

- sc classes: SwingOSC (aliveThread has longer timeout, improved isLocal detection), JavaObject (added print, isNull, notNull methods), extSwingOSC (fixed asSwingArg implementations, removed jinspect, jplot, jmakeWindow, jscope, jbrowse)
- sc gui classes: JSCWindow (added resizable_, redefined drawHook refresh policy, cocoa-bounds translation look-and-feel independant, added scroll argument to contructor), JSCNumberBox (drag'n'drop fixed), JSCTextField (drag'n'drop fixed), JSCUserView (added mousePosition, clearOnRefresh_ methods), JSCPlug(Container)View (improved doesNotUnderstand), JSCView (proper layout manager validation with bounds_ and visible_, added addAction and removeAction methods), SwingGUI (added tabletView, scrollView), extCocoaCompat (removed methods that have been added to the standard library), JSCTextView (fixed property changes when document is empty), removed JSCScrollPane, JStartRow, added JSCScrollView, JSCScrollTopView, JSCTabletView
- sc helper classes improvements: Collapse (function call error protection), Insets (added leftTop method), added UpdateListener
- sc help files: completed, partly reformatted
- java classes: SwingOSC (fixed checkMethodArgs type priorities)
- java gui classes: ActionResponder (bug fix), WindowResponder (bounds-to-cocoa translation), ColliderLayout (to work with scrollview), MouseResponder and ComponentResponder (to work with relativeOrigin parents), ContentPane (extracted from Frame), DummyTransferHandler (preserve clipboard cut/copy/paste actions), Frame (scroll support, cocoa-bounds translation, setAlpha method), NumberField (String based setNumber method to avoid roundoff errors), Pen (fixed stroke shape transform when shearing, support for relativeOrigin, bug fixes), RangeSlider (more pretty knob scaling)
- java helper classes: AudioFile (added retrieveType method)

#### v0.56 (oct 2007)

- sc and java classes: bug fixes (alpha tranparency, FlowView support)

#### v0.55 (sep 2007)

- added tutorial from the den haag symposium
- sc classes: bug fixes, enhancements in JavaObject
- java classes: updates and compatibility with Forest/Timebased project

#### v0.54 (jul 2007)

- osc commands: added remove and update commands to "/classes"
- sc classes: added JSCScrollBar, updated SwingGUI, SwingOSC, caching option for JSCSoundFileView, curve shapes for JSCEnvelopeView

#### v0.53 (jul 2007)

- updated NetUtil, assuring UTF-8 string encoding
- fixed -h option
- sc classes: updated SwingGUI, crucial support, various fixes

#### v0.52 (apr 2007)

- bug fixes: JSCWindow-bounds
- new classes: JKeyState, JStartRow, SwingGUI
- help files converted to HTML (c. 2/3 still need proper clean-up though)

#### v0.513 (apr 2007)

- fixes a number of known issues (JSCView.bounds_, JSCEnvelopeView.value_, JSCPopUpMenu.item_, JSCListView.item_)

#### v0.51 (mar 2007)

- includes NetUtil 0.32 (= fixes umlaut problems)
- using Apache Ant now for building
- removed non-breaking-spaces from help files (= avoids PsyCollider bug)
- bug fixes in SC classes: continuous text/number updates while typing in JSCTextField, JSCNumberBox ; graphics glitches with JSCSoundFileView and JSCEnvelopeView on Linux/Windows ; bounds updates when parent views move

#### v0.50 (feb 2007)

- java classes: fixed opacity and background colour issues. added layout managers for supercollider, added AbstractMultiSlider, EnvelopeView, TextView, DocumentResponder, ActionMessenger. lot's of fixes and improvement (MovieView, RangeSlider, SoundFileView, Pen, MouseResponder, Frame)
- sc classes: added JSCEnvelopeView, finished JSCTextView, fixed JSCCompositeView, JSCHLayoutView, JSCVLayoutView, added support for elastic views. Dozens of fixes and improvements (JPen, JSlider, JRangeSlider, JSCSoundFileView, JSCMovieView, JSCWindow, JFont, JEZSlider, JEZNumber, probably others)
- .sh shell scripts now specify Gtk+ look-and-feel. Edit them if you want to return to metal look-and-feel.

#### v0.44 (dec 2006)

- new sc classes: `JSCSoundFileView`, `JSCMovieView`, `JSCTabbedPane`, `JSCCheckBox`
- fixes: `JFont`, `JSCTextField`, `JPen`

#### v0.43 (oct 2006)

- sc classes: `JSCMultiSliderView`

#### v0.42 (oct 2006)

- adds dynamic class loading and `/classes` OSC command
- uses updated NetUtil, and hence has TCP server mode (TCP is default now)
- renamed `OSCClient.java` to `SwingClient.java`
- sc classes: fixes (keyboard actions in `JSC2DSlider`, opacity in `JSCCompositeView`, focus in `JSCSlider`), missing classes (`SwingDialog`), modifications (string operations in `JPen`)
- error messages are printed to `System.out` not `System.err`, so they are visible in SuperCollider's post window
- v0.421 makes `new()` and `start()` in `SwingOSC.java` public (e.g. to be accessible by Eisenkraut)

#### v0.41 (aug 2006)

- fixes for `JSCCompositeView`, completions for `JSCWindow`
- includes `JSCPlugView`, `JSCPlugContainerView`, `JavaObject`

#### v0.40 (apr 2006)

- OSC syntax change: using nested blob'ed OSC messages is deprecated ; instead nesting is achieved by using special string arguments. this makes SwingOSC really usable in other clients such as Pure Data.
- added first examples for Pure Data
- sc classes: all modified to use the new OSC syntax. added `JPen`, `JSCUserView`, `JSCTextView`, fixed `JSCHLayoutView` and `JSCVLayoutView`, added mouse, component resize and focus traversal tracking, modified the `JMouseBase` gui, optimized performance, fixed a lot of bugs.
- `MultiStateButton` was moved to the `de.sciss.gui` package and is slightly modified.

#### v0.39 (mar 2006)

- sc classes: SwingOSC.sc : booting now works. Help file updated

#### v0.38 (feb 2006)

- sc classes: finished `JStethoscope` / `JSCScope` / `.jscope` plusGUI
- sc classes: converted `FreqScope` by Lance Putnam
- added `-h` option

#### v0.37 (feb 2006)

- cleanup and slight performance improvisation
- added `/field` and `/fieldr` commands
- messages whose arguments contain nested messages are evaluated strictly sequentially, making side effects much more stringent
- bug fixes: `/free`
- removed `"toolkit"` object assignment which caused the `-i` option to be ineffective. you can restore the original binding by sending a message `[ "/local", \toolkit, [ "/method", "java.awt.Toolkit", \getDefaultToolkit ]]`

#### v0.36 (dec 2005)

- added `JSCDragSource/Sink/Both` supercollider classes
- added keyboard + drag'n'drop support in supercollider classes
- optimization and fixes in supercollider classes

#### v0.35 (dec 2005)

- switched to Eclipse for development
- added `RangeSlider` and `Slider2D` classes (+ related SC classes)
- added `JMacUGens.sc` supercollider class
- added `/import` package lookup mechanism (not yet accessible though)

#### v0.3 (nov 2005)

- reworked (new) OSC command structure
- prelimary SC classes

#### v0.2 (aug 2005)

- includes example of the possibility to instantiate applets (nice for integrating Proce55ing)

java is a trademark of sun microsystems
i think mac os and xcode are trademarks of apple inc
windows is one of microsoft corp
jever is a trademark of some west german beer factory