Merge pull request #87 from Sciss/work

v2.1.0

Author: Sciss

README.md

@@ -16,7 +16,7 @@ The widget class hierarchy loosely resembles that of Java Swing. The main differ
   In scala-swing, components that can have child components extend the Container trait.
 - Layout managers and panels are coupled. There is no way to exchange the layout manager
   of a panel. As a result, the layout constraints for widgets can be typed. 
-  (Note that you gain more type-safety and don't loose much flexibility here. Besides 
+  (Note that you gain more type-safety and do not loose much flexibility here. Besides 
   being not a common operation, exchanging the layout manager of a panel in Java 
   Swing almost always leads to exchanging the layout constraints for every of the panel's 
   child component. In the end, it is not more work to move all children to a newly created 
@@ -25,8 +25,8 @@ The widget class hierarchy loosely resembles that of Java Swing. The main differ
   collection. The typical usage style is to create anonymous subclasses of the widgets to
   customize their properties, and nest children and event reactions.
 - The scala-swing event system follows a different approach than the underlying Java system.
-  Instead of add event listeners with a particular interface (such as `java.awt.ActionListener`),
-  a `Reactor` instances announces the interest in receiving events by calling `listenTo` for
+  Instead of adding event listeners with a particular interface (such as `java.awt.ActionListener`),
+  a `Reactor` instance announces the interest in receiving events by calling `listenTo` for
   a `Publisher`. Publishers are also reactors and listen to themselves per default as a convenience.
   A reactor contains an object `reactions` which serves as a convenient place to register observers
   by adding partial functions that pattern match for any event that the observer is interested in.
@@ -117,3 +117,4 @@ at [http://www.scala-lang.org/documentation/api.html](http://www.scala-lang.org/
 ## Current Work
 
 Current changes are being made on the `work` branch.
+Last published version is found on the `main` branch.

build.sbt

@@ -4,7 +4,7 @@ scalaModuleSettings
 
 name               := "scala-swing"
 
-version            := "2.1.0-SNAPSHOT"
+version            := "2.1.0"
 
 scalacOptions in ThisBuild ++= Seq("-deprecation", "-feature")
 

src/main/scala/scala/swing/package.scala

@@ -8,9 +8,73 @@
 
 package scala
 
-/**
- * Useful imports that do not have wrappers.
- */
+/** Scala-swing is a graphical user interface library that will wrap most of Java Swing
+  * for Scala in a straightforward manner.
+  *
+  * ==Overview==
+  *
+  * The widget class hierarchy loosely resembles that of Java Swing.
+  * The main differences are:
+  *
+  *  - In Java Swing all components are containers per default. This does not make much sense for a number
+  *    of components, like [[scala.swing.TextField]], [[scala.swing.CheckBox]], [[scala.swing.RadioButton]],
+  *    and so on. Our guess is that this architecture
+  *    was chosen because Java lacks multiple inheritance. In scala-swing, components that can have child
+  *    components extend the [[scala.swing.Container]] trait.
+  *  - Layout managers and panels are coupled. There is no way to exchange the layout manager of a panel.
+  *    As a result, the layout constraints for widgets can be typed. (Note that you gain more type-safety
+  *    and do not loose much flexibility here. Besides being not a common operation, exchanging the layout
+  *    manager of a panel in Java Swing almost always leads to exchanging the layout constraints for every
+  *    of the panel's child component. In the end, it is not more work to move all children to a newly
+  *    created panel.)
+  *  - Widget hierarchies are built by adding children to their parent container's contents collection.
+  *    The typical usage style is to create anonymous subclasses of the widgets to customize their
+  *    properties, and nest children and event reactions.
+  *  - The scala-swing event system follows a different approach than the underlying Java system. Instead
+  *    of adding event listeners with a particular interface (such as `java.awt.ActionListener`),
+  *    a [[scala.swing.Reactor]]
+  *    instance announces the interest in receiving events by calling `listenTo` for a [[scala.swing.Publisher]].
+  *    Publishers
+  *    are also reactors and listen to themselves per default as a convenience. A reactor contains an object
+  *    `reactions` which serves as a convenient place to register observers by adding partial functions that
+  *    pattern match for any event that the observer is interested in. This is shown in the examples section
+  *    below.
+  *  - For more details see [[https://github.com/scala/scala-swing/blob/work/docs/SIP-8.md SIP-8]].
+  *
+  * Scala-swing comprises two main packages:
+  *
+  *  - `scala.swing`: All widget classes and traits.
+  *  - `scala.swing.event`: The event hierarchy.
+  *
+  * This package object contains useful type aliases that do not have wrappers.
+  *
+  * ==Examples==
+  *
+  * The following example shows how to plug components and containers together and react to a
+  * mouse click on a button:
+  *
+  * {{{
+  * import scala.swing._
+  *
+  * new Frame {
+  *   title = "Hello world"
+  *
+  *   contents = new FlowPanel {
+  *     contents += new Label("Launch rainbows:")
+  *     contents += new Button("Click me") {
+  *       reactions += {
+  *         case event.ButtonClicked(_) =>
+  *           println("All the colours!")
+  *       }
+  *     }
+  *   }
+  *
+  *   pack()
+  *   centerOnScreen()
+  *   open()
+  * }
+  * }}}
+  */
 package object swing {
   type Point      = java.awt.Point
   type Dimension  = java.awt.Dimension