From b95390021d9f95fd92e54785c68a29e3e04476a0 Mon Sep 17 00:00:00 2001 From: Ingo Maier Date: Mon, 27 Oct 2008 16:35:04 +0000 Subject: added some swing scaladocs --- src/swing/scala/swing/Action.scala | 4 +- src/swing/scala/swing/Alignment.scala | 2 + src/swing/scala/swing/BorderPanel.scala | 9 +++- src/swing/scala/swing/Button.scala | 2 +- src/swing/scala/swing/CheckBox.scala | 2 +- src/swing/scala/swing/ComboBox.scala | 26 +++++------ src/swing/scala/swing/Component.scala | 2 +- src/swing/scala/swing/Container.scala | 3 ++ src/swing/scala/swing/Dialog.scala | 16 +++++++ src/swing/scala/swing/FileChooser.scala | 3 +- src/swing/scala/swing/FlowPanel.scala | 2 +- src/swing/scala/swing/FormattedTextField.scala | 5 +++ src/swing/scala/swing/Frame.scala | 2 +- src/swing/scala/swing/GUIApplication.scala | 3 ++ src/swing/scala/swing/GridBagPanel.scala | 6 ++- src/swing/scala/swing/GridPanel.scala | 1 + src/swing/scala/swing/Label.scala | 2 +- src/swing/scala/swing/ListView.scala | 57 ++++++++++++++++++++---- src/swing/scala/swing/MainFrame.scala | 4 +- src/swing/scala/swing/Menu.scala | 16 ++++--- src/swing/scala/swing/PasswordField.scala | 2 + src/swing/scala/swing/ProgressBar.scala | 4 ++ src/swing/scala/swing/Publisher.scala | 27 +++++++---- src/swing/scala/swing/Reactions.scala | 6 ++- src/swing/scala/swing/Reactor.scala | 8 +++- src/swing/scala/swing/ScrollPane.scala | 15 ++++++- src/swing/scala/swing/Scrollable.scala | 2 +- src/swing/scala/swing/SequentialContainer.scala | 5 ++- src/swing/scala/swing/SimpleGUIApplication.scala | 4 ++ src/swing/scala/swing/Slider.scala | 2 + src/swing/scala/swing/SplitPane.scala | 4 ++ src/swing/scala/swing/TabbedPane.scala | 7 +++ src/swing/scala/swing/Table.scala | 7 +++ src/swing/scala/swing/ToggleButton.scala | 3 +- src/swing/scala/swing/UIElement.scala | 6 ++- 35 files changed, 208 insertions(+), 61 deletions(-) (limited to 'src/swing') diff --git a/src/swing/scala/swing/Action.scala b/src/swing/scala/swing/Action.scala index 46dc470558..c3a94ed65e 100644 --- a/src/swing/scala/swing/Action.scala +++ b/src/swing/scala/swing/Action.scala @@ -34,10 +34,12 @@ object Action { } /** + * An abstract action to be performed in reaction to user input. + * * Not every action component will honor every property of its action. * An action itself can generally be configured so that certain properties * should be ignored and instead taken from the component directly. In the - * end, it is up to a component, which property it uses in which way. + * end, it is up to a component which property it uses in which way. * * @see javax.swing.Action */ diff --git a/src/swing/scala/swing/Alignment.scala b/src/swing/scala/swing/Alignment.scala index 524fefe92e..e4875904c8 100644 --- a/src/swing/scala/swing/Alignment.scala +++ b/src/swing/scala/swing/Alignment.scala @@ -5,6 +5,8 @@ import javax.swing.SwingConstants._ /** * Horizontal and vertical alignments. We sacrifice a bit of type-safety * for simplicity here. + * + * @see javax.swing.SwingConstants */ object Alignment extends Enumeration { val Left = Value(LEFT) diff --git a/src/swing/scala/swing/BorderPanel.scala b/src/swing/scala/swing/BorderPanel.scala index 93ee4eec71..4b614272e3 100644 --- a/src/swing/scala/swing/BorderPanel.scala +++ b/src/swing/scala/swing/BorderPanel.scala @@ -3,6 +3,9 @@ package scala.swing import java.awt.BorderLayout object BorderPanel { + /** + * The position of a component in a BorderPanel + */ object Position extends Enumeration { val North = Value(BorderLayout.NORTH) val South = Value(BorderLayout.SOUTH) @@ -20,6 +23,10 @@ object BorderPanel { } /** + * A container that arranges its children around a central component that + * takes most of the space. The other children are placed on one of four + * borders: north, east, south, west. + * * @see javax.swing.BorderLayout */ class BorderPanel extends Panel with LayoutContainer { @@ -34,6 +41,4 @@ class BorderPanel extends Panel with LayoutContainer { protected def areValid(c: Constraints): (Boolean, String) = (true, "") protected def add(c: Component, l: Constraints) { peer.add(c.peer, l.toString) } - - } diff --git a/src/swing/scala/swing/Button.scala b/src/swing/scala/swing/Button.scala index 3e3e05aa8f..0aa93ae45b 100644 --- a/src/swing/scala/swing/Button.scala +++ b/src/swing/scala/swing/Button.scala @@ -4,7 +4,7 @@ import javax.swing._ import event._ /** - * A button that can be pushed, usually to perfrom some action. + * A button that can be clicked, usually to perform some action. * * @see javax.swing.JButton */ diff --git a/src/swing/scala/swing/CheckBox.scala b/src/swing/scala/swing/CheckBox.scala index 199179d83b..845b7f7024 100644 --- a/src/swing/scala/swing/CheckBox.scala +++ b/src/swing/scala/swing/CheckBox.scala @@ -3,7 +3,7 @@ package scala.swing import javax.swing._ /** - * Two state button that can be either be checked or not. + * Two state button that can either be checked or unchecked. * * @see javax.swing.JCheckBox */ diff --git a/src/swing/scala/swing/ComboBox.scala b/src/swing/scala/swing/ComboBox.scala index 4e400e726c..219972d22f 100644 --- a/src/swing/scala/swing/ComboBox.scala +++ b/src/swing/scala/swing/ComboBox.scala @@ -9,7 +9,7 @@ object ComboBox { /** * An editor for a combo box. Let's you edit the currently selected item. * It is highly recommended to use the BuiltInEditor class. For anything - * else, one cannot guarantee that it integrated nicely into the current + * else, one cannot guarantee that it integrates nicely with the current * LookAndFeel. * * Publishes action events. @@ -138,14 +138,8 @@ object ComboBox { } /** - * Has built-in default editor and renderer that cannot be exposed. - * They are set by the look and feel (LaF). Unfortunately, this design in - * inherently broken, since custom editors will almost always look - * differently. The border of the built-in text field editor, e.g., is drawn - * by the LaF. In a custom text field editor we have no way to mirror that. - * - * This combo box has to be initialized with a valid selected value. - * Otherwise it will fail. + * Let's the user make a selection from a list of predefined items. Visually, + * this is implemented as a button-like component with a pull-down menu. * * @see javax.swing.JComboBox */ @@ -165,15 +159,15 @@ class ComboBox[A](items: Seq[A]) extends Component with Publisher { /** * Sets the renderer for this combo box's items. Index -1 is - * passed to the renderer for the selected item (not in the popup menu). + * passed to the renderer for the selected item (not in the pull-down menu). * - * The underlying combo box renders all items in a ListView (both, in - * the pulldown menu as well as in the box itself), hence the - * ListView.Renderer. + * The underlying combo box renders all items in a ListView + * (both, in the pull-down menu as well as in the box itself), hence the + * ListView.Renderer. * * Note that the UI peer of a combo box usually changes the colors - * of the component to its own defaults _after_ the renderer has configured it. - * That's Swing's principle of most suprise. + * of the component to its own defaults _after_ the renderer has been + * configured. That's Swing's principle of most suprise. */ def renderer: ListView.Renderer[A] = ListView.Renderer.wrap(peer.getRenderer) def renderer_=(r: ListView.Renderer[A]) { peer.setRenderer(r.peer) } @@ -185,7 +179,7 @@ class ComboBox[A](items: Seq[A]) extends Component with Publisher { def editable: Boolean = peer.isEditable /** - * Makes this combo box editable. In order to do, this combo needs an + * Makes this combo box editable. In order to do so, this combo needs an * editor which is supplied by the implicit argument. For default * editors, see ComboBox companion object. */ diff --git a/src/swing/scala/swing/Component.scala b/src/swing/scala/swing/Component.scala index 0677761d5f..6409ff1cd5 100644 --- a/src/swing/scala/swing/Component.scala +++ b/src/swing/scala/swing/Component.scala @@ -124,7 +124,7 @@ abstract class Component extends UIElement with Publisher { }) /** - * Contains publishers for various mouse events. They are subdivided for + * Contains publishers for various mouse events. They are separated for * efficiency reasons. */ object Mouse { diff --git a/src/swing/scala/swing/Container.scala b/src/swing/scala/swing/Container.scala index c1a2c7cc32..d51b056aba 100644 --- a/src/swing/scala/swing/Container.scala +++ b/src/swing/scala/swing/Container.scala @@ -4,6 +4,9 @@ import event._ import scala.collection.mutable.Buffer object Container { + /** + * Utility trait for wrapping containers. + */ trait Wrapper extends Component with Container { protected val _contents = new Content def contents: Seq[Component] = _contents diff --git a/src/swing/scala/swing/Dialog.scala b/src/swing/scala/swing/Dialog.scala index 05928b5dc1..d2cab71c9a 100644 --- a/src/swing/scala/swing/Dialog.scala +++ b/src/swing/scala/swing/Dialog.scala @@ -2,7 +2,15 @@ package scala.swing import javax.swing.{Icon, JOptionPane} +/** + * Simple predefined dialogs. + * + * @see javax.swing.JOptionPane + */ object Dialog { + /** + * The message type of a dialog. + */ object Message extends Enumeration { val Error = Value(JOptionPane.ERROR_MESSAGE) val Info = Value(JOptionPane.INFORMATION_MESSAGE) @@ -10,12 +18,20 @@ object Dialog { val Question = Value(JOptionPane.QUESTION_MESSAGE) val Plain = Value(JOptionPane.PLAIN_MESSAGE) } + + /** + * The possible answers a user can select. + */ object Options extends Enumeration { val Default = Value(JOptionPane.DEFAULT_OPTION) val YesNo = Value(JOptionPane.YES_NO_OPTION) val YesNoCancel = Value(JOptionPane.YES_NO_CANCEL_OPTION) val OkCancel = Value(JOptionPane.OK_CANCEL_OPTION) } + + /** + * The selected result of dialog. + */ object Result extends Enumeration { val Yes = Value(JOptionPane.YES_OPTION) val Ok = Yes diff --git a/src/swing/scala/swing/FileChooser.scala b/src/swing/scala/swing/FileChooser.scala index 92bf3c54e1..cab6abc1c0 100644 --- a/src/swing/scala/swing/FileChooser.scala +++ b/src/swing/scala/swing/FileChooser.scala @@ -7,7 +7,8 @@ import javax.swing.filechooser._ object FileChooser { /** * The result of a file dialog. The precise meaning of the Approve - * result depends on the specific dialog kind. + * result depends on the specific dialog type. Could be "save" or "open" for + * example. */ object Result extends Enumeration { val Cancel = Value(JFileChooser.CANCEL_OPTION) diff --git a/src/swing/scala/swing/FlowPanel.scala b/src/swing/scala/swing/FlowPanel.scala index 3c3c7d1f31..f8eb00a71e 100644 --- a/src/swing/scala/swing/FlowPanel.scala +++ b/src/swing/scala/swing/FlowPanel.scala @@ -13,7 +13,7 @@ object FlowPanel { } /** - * A panel that lays out its contents horizontally, one after the other. + * A panel that arranges its contents horizontally, one after the other. * If they don't fit, this panel will try to insert line breaks. * * @see java.awt.FlowLayout diff --git a/src/swing/scala/swing/FormattedTextField.scala b/src/swing/scala/swing/FormattedTextField.scala index b771078f37..4be61b6cb1 100644 --- a/src/swing/scala/swing/FormattedTextField.scala +++ b/src/swing/scala/swing/FormattedTextField.scala @@ -5,6 +5,9 @@ import java.awt.event._ import event._ object FormattedTextField { + /** + * The behavior of a formatted text field when it loses its focus. + */ object FocusLostBehavior extends Enumeration { val Commit = Value(JFormattedTextField.COMMIT) val CommitOrRevert = Value(JFormattedTextField.COMMIT_OR_REVERT) @@ -14,6 +17,8 @@ object FormattedTextField { } /** + * A text field with formatted input. + * * @see javax.swing.JFormattedTextField */ class FormattedTextField(format: java.text.Format) extends TextComponent { diff --git a/src/swing/scala/swing/Frame.scala b/src/swing/scala/swing/Frame.scala index 9d0162356f..fc2ebe297d 100644 --- a/src/swing/scala/swing/Frame.scala +++ b/src/swing/scala/swing/Frame.scala @@ -4,7 +4,7 @@ import javax.swing._ import event._ /** - * A decorated window. + * A window with decoration such as a title, border, and action buttons. * * @see javax.swing.JFrame */ diff --git a/src/swing/scala/swing/GUIApplication.scala b/src/swing/scala/swing/GUIApplication.scala index e008b5422d..999ef3971f 100644 --- a/src/swing/scala/swing/GUIApplication.scala +++ b/src/swing/scala/swing/GUIApplication.scala @@ -11,6 +11,9 @@ class GUIApplication { //JFrame.setDefaultLookAndFeelDecorated(defaultLookAndFeelDecorated) } + /** + * Initializes the framework and runs the given program. + */ def run(prog: => Unit): Unit = SwingUtilities.invokeLater { new Runnable() { diff --git a/src/swing/scala/swing/GridBagPanel.scala b/src/swing/scala/swing/GridBagPanel.scala index 8e42de28a1..d27299b023 100644 --- a/src/swing/scala/swing/GridBagPanel.scala +++ b/src/swing/scala/swing/GridBagPanel.scala @@ -33,7 +33,7 @@ object GridBagPanel { } /** - * A panel that lays out its children in a grid. Layout details can be + * A panel that arranges its children in a grid. Layout details can be * given for each cell of the grid. * * @see java.awt.GridBagLayout @@ -44,6 +44,10 @@ class GridBagPanel extends Panel with LayoutContainer { private def layoutManager = peer.getLayout.asInstanceOf[java.awt.GridBagLayout] + /** + * Convenient conversion from xy-coords given as pairs to + * grid bag constraints. + */ implicit def pair2Constraints(p: (Int, Int)): Constraints = { val c = new Constraints c.gridx = p._1 diff --git a/src/swing/scala/swing/GridPanel.scala b/src/swing/scala/swing/GridPanel.scala index 0d92b8117f..1a1de23d2a 100644 --- a/src/swing/scala/swing/GridPanel.scala +++ b/src/swing/scala/swing/GridPanel.scala @@ -6,6 +6,7 @@ object GridPanel { /** * A panel that lays out its contents in a uniform grid. + * * @see java.awt.GridLayout */ class GridPanel(rows0: Int, cols0: Int) extends Panel with SequentialContainer.Wrapper { diff --git a/src/swing/scala/swing/Label.scala b/src/swing/scala/swing/Label.scala index 40189475aa..defa45fa01 100644 --- a/src/swing/scala/swing/Label.scala +++ b/src/swing/scala/swing/Label.scala @@ -4,7 +4,7 @@ import javax.swing._ import scala.swing.Swing._ /** - * A label component. + * A label component that display either a text, an icon, or both. * * @see javax.swing.JLabel */ diff --git a/src/swing/scala/swing/ListView.scala b/src/swing/scala/swing/ListView.scala index 6d9a6354bf..81581a5a9e 100644 --- a/src/swing/scala/swing/ListView.scala +++ b/src/swing/scala/swing/ListView.scala @@ -6,6 +6,9 @@ import event._ import java.awt.Color object ListView { + /** + * The supported modes of user selections. + */ object IntervalMode extends Enumeration { val Single = Value(ListSelectionModel.SINGLE_SELECTION) val SingleInterval = Value(ListSelectionModel.SINGLE_INTERVAL_SELECTION) @@ -19,23 +22,43 @@ object ListView { object Renderer { def wrap[A](r: ListCellRenderer): Renderer[A] = new Wrapped[A](r) + /** + * Wrapper for javax.swing.ListCellRenderers + */ class Wrapped[A](override val peer: ListCellRenderer) extends Renderer[A] { def componentFor(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: A, index: Int) = { Component.wrap(peer.getListCellRendererComponent(list.peer, a, index, isSelected, hasFocus).asInstanceOf[JComponent]) } } + /** + * Returns a renderer for items of type A. The given function + * converts items of type A to items of type B + * for which a renderer is implicitly given. This allows chaining of + * renderers, e.g.: + * + * + * case class Person(name: String, email: String) + * val persons = List(Person("John", "j.doe@a.com"), Person("Mary", "m.jane@b.com")) + * new ListView(persons) { + * renderer = ListView.Renderer(_.name) + * } + * + */ def apply[A,B](f: A => B)(implicit renderer: Renderer[B]): Renderer[A] = new Renderer[A] { def componentFor(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: A, index: Int): Component = renderer.componentFor(list, isSelected, hasFocus, f(a), index) } } - /*def Renderer[A,B](f: A => B)(implicit renderer: Renderer[B]): Renderer[A] = new Renderer[A] { - def componentFor(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: A, index: Int): Component = - renderer.componentFor(list, isSelected, hasFocus, f(a), index) - }*/ - + /** + * Item renderer for a list view. This is contravariant on the type of the + * items, so a more general renderer can be used in place of a more specific + * one. For instance, an Any renderer can be used for a list view + * of strings. + * + * @see javax.swing.ListCellRenderer + */ abstract class Renderer[-A] { def peer: ListCellRenderer = new ListCellRenderer { def getListCellRendererComponent(list: JList, a: Any, index: Int, isSelected: Boolean, hasFocus: Boolean) = @@ -47,7 +70,7 @@ object ListView { /** * A default renderer that maintains a single component for item rendering * and preconfigures it to sensible defaults. It is polymorphic on the - * components type so clients can easily use component specific attributes + * component's type so clients can easily use component specific attributes * during configuration. */ abstract class AbstractRenderer[-A, C<:Component](protected val component: C) extends Renderer[A] { @@ -58,6 +81,8 @@ object ListView { /** * Standard preconfiguration that is commonly done for any component. + * This includes foreground and background colors, as well as colors + * of item selections. */ def preConfigure(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: A, index: Int) { if (isSelected) { @@ -83,6 +108,11 @@ object ListView { } } + /** + * A generic renderer that uses Swing's built-in renderers. If there is no + * specific renderer for a type, this renderer falls back to a renderer + * that renders the string returned from an item's toString. + */ implicit object GenericRenderer extends Renderer[Any] { override lazy val peer: ListCellRenderer = new DefaultListCellRenderer def componentFor(list: ListView[_], isSelected: Boolean, hasFocus: Boolean, a: Any, index: Int): Component = { @@ -94,8 +124,10 @@ object ListView { } /** - * A component that displays its elements in a list. Named - * ListView to avoid a clash with the frequently used + * A component that displays a number of elements in a list. A list view does + * not support inline editing of items. If you need it, use a table view instead. + * + * Named ListView to avoid a clash with the frequently used * scala.List * * @see javax.swing.JList @@ -134,6 +166,9 @@ class ListView[A] extends Component { }) } + /** + * The current item selection. + */ object selection extends Publisher { protected abstract class Indices[A](a: =>Seq[A]) extends scala.collection.mutable.Set[A] { def -=(n: A) @@ -143,6 +178,9 @@ class ListView[A] extends Component { def elements = a.elements } + /** + * The indices of the currently selected items. + */ object indices extends Indices(peer.getSelectedIndices) { def -=(n: Int) { peer.removeSelectionInterval(n,n) } def +=(n: Int) { peer.addSelectionInterval(n,n) } @@ -152,6 +190,9 @@ class ListView[A] extends Component { } def selectIndices(ind: Int*) = peer.setSelectedIndices(ind.toArray) + /** + * The currently selected items. + */ object items extends SeqProxy[A] { def self = peer.getSelectedValues.map(_.asInstanceOf[A]) def leadIndex: Int = peer.getSelectionModel.getLeadSelectionIndex diff --git a/src/swing/scala/swing/MainFrame.scala b/src/swing/scala/swing/MainFrame.scala index 018866ba2b..ae594448ef 100644 --- a/src/swing/scala/swing/MainFrame.scala +++ b/src/swing/scala/swing/MainFrame.scala @@ -3,8 +3,8 @@ package scala.swing import event._ /** - * A frame that can be used for main application windows. Quits the - * application on close. + * A frame that can be used for main application windows. Shuts down the + * framework and quits the application when closed. */ class MainFrame extends Frame { reactions += { diff --git a/src/swing/scala/swing/Menu.scala b/src/swing/scala/swing/Menu.scala index 418439435d..7f85688125 100644 --- a/src/swing/scala/swing/Menu.scala +++ b/src/swing/scala/swing/Menu.scala @@ -4,6 +4,8 @@ import scala.collection.mutable._ import javax.swing._ /** + * A menu bar. Each window can contain at most one. Contains a number of menus. + * * @see javax.swing.JMenuBar */ class MenuBar extends Component with SequentialContainer.Wrapper { @@ -16,13 +18,9 @@ class MenuBar extends Component with SequentialContainer.Wrapper { //def helpMenu_=(m: Menu) { peer.setHelpMenu(m.peer) } } -/*trait MenuElement extends Component { - def peer: javax.swing.JComponent with javax.swing.MenuElement - - def subElements: Seq[MenuElement] = peer.getSubElements.map(Component.wrapperFor(_)) -}*/ - /** + * A menu item that can be used in a menu. + * * @see javax.swing.JMenuItem */ class MenuItem(title0: String) extends AbstractButton { @@ -34,6 +32,8 @@ class MenuItem(title0: String) extends AbstractButton { } /** + * A menu. Contains menu items. Being a menu item itself, menus can be nested. + * * @see javax.swing.JMenu */ class Menu(title0: String) extends MenuItem(title0) with SequentialContainer.Wrapper { self: Menu => @@ -41,12 +41,16 @@ class Menu(title0: String) extends MenuItem(title0) with SequentialContainer.Wra } /** + * A menu item with a radio button. + * * @see javax.swing.JRadioButtonMenuItem */ class RadioMenuItem(title0: String) extends MenuItem(title0) { override lazy val peer: JRadioButtonMenuItem = new JRadioButtonMenuItem(title0) } /** + * A menu item with a check box. + * * @see javax.swing.JCheckBoxMenuItem */ class CheckMenuItem(title0: String) extends MenuItem(title0) { diff --git a/src/swing/scala/swing/PasswordField.scala b/src/swing/scala/swing/PasswordField.scala index 58a4150fb8..4769759a0c 100644 --- a/src/swing/scala/swing/PasswordField.scala +++ b/src/swing/scala/swing/PasswordField.scala @@ -5,6 +5,8 @@ import java.awt.event._ import event._ /** + * A password field, that displays a replacement character for each character in the password. + * * @see javax.swing.JPasswordField */ class PasswordField(text0: String, columns0: Int) extends TextField(text0, columns0) { diff --git a/src/swing/scala/swing/ProgressBar.scala b/src/swing/scala/swing/ProgressBar.scala index 463c2fba56..68d815f181 100644 --- a/src/swing/scala/swing/ProgressBar.scala +++ b/src/swing/scala/swing/ProgressBar.scala @@ -3,6 +3,10 @@ package scala.swing import event._ /** + * A bar indicating progress of some action. Can be in indeterminate mode, + * in which it indicates that the action is in progress (usually by some + * animation) but does not indicate the amount of work done or to be done. + * * @see javax.swing.JProgressBar */ class ProgressBar extends Component with Orientable { diff --git a/src/swing/scala/swing/Publisher.scala b/src/swing/scala/swing/Publisher.scala index bcefc6c42e..4b26e9e74e 100644 --- a/src/swing/scala/swing/Publisher.scala +++ b/src/swing/scala/swing/Publisher.scala @@ -4,26 +4,35 @@ import scala.collection.mutable._ import event.Event /** - * Notifies subscribed observers when a event is published. + * Notifies registered reactions when an event is published. Publishers are also + * reactors and listen to themselves per default as a convenience. + * + * In order to reduce memory leaks, reactions are weakly referenced by default, + * unless they implement Reactions.StronglyReferenced. This way, + * the lifetime of reactions are more easily bound to the registering object, + * which are reactors in common client code and hold strong references to their + * reactions. As a result, reactors can be garbage collected even though they + * still have reactions registered at some publisher, but usually not vice versa + * since reactors (strongly) reference publishers they are interested in. */ trait Publisher extends Reactor { import Reactions._ - // TODO: optionally weak references - protected var listeners = new RefSet[Reaction] { + + protected val listeners = new RefSet[Reaction] { import scala.ref._ val underlying = new HashSet[Reference[Reaction]] protected def Ref(a: Reaction) = a match { - case a: StronglyReferenced => new StrongReference[Reaction](a) with super.Ref[Reaction] { - type _$1 = Reaction // FIXME: what's going on here? - } - case _ => new WeakReference[Reaction](a, referenceQueue) with super.Ref[Reaction] { - type _$1 = Reaction // FIXME: what's going on here? - } + case a: StronglyReferenced => new StrongReference[Reaction](a) with super.Ref[Reaction] + case _ => new WeakReference[Reaction](a, referenceQueue) with super.Ref[Reaction] } } def subscribe(listener: Reaction) { listeners += listener } def unsubscribe(listener: Reaction) { listeners -= listener } + + /** + * Notify all registered reactions. + */ def publish(e: Event) { for (val l <- listeners) l(e) } listenTo(this) diff --git a/src/swing/scala/swing/Reactions.scala b/src/swing/scala/swing/Reactions.scala index fce1fe3956..8d5c4ae576 100644 --- a/src/swing/scala/swing/Reactions.scala +++ b/src/swing/scala/swing/Reactions.scala @@ -21,7 +21,7 @@ object Reactions { /** * A Reaction implementing this trait is strongly referenced in the reaction list */ - trait StronglyReferenced // TODO: implement in Publisher + trait StronglyReferenced class Wrapper(listener: Any)(r: Reaction) extends Reaction with StronglyReferenced with Proxy { def self = listener @@ -30,7 +30,9 @@ object Reactions { } } - +/** + * Used by reactors to let clients register custom event reactions. + */ abstract class Reactions extends Reactions.Reaction { /** * Add a reaction. diff --git a/src/swing/scala/swing/Reactor.scala b/src/swing/scala/swing/Reactor.scala index 002002d3f9..1b2d806d85 100644 --- a/src/swing/scala/swing/Reactor.scala +++ b/src/swing/scala/swing/Reactor.scala @@ -1,7 +1,13 @@ package scala.swing +/** + * The counterpart to publishers. Listens to events from registered publishers. + */ trait Reactor { - val reactions = new Reactions.Impl + /** + * All reactions of this reactor. + */ + val reactions: Reactions = new Reactions.Impl /** * Listen to the given publisher as long as deafTo isn't called for * them. diff --git a/src/swing/scala/swing/ScrollPane.scala b/src/swing/scala/swing/ScrollPane.scala index a451745631..a3eea8a715 100644 --- a/src/swing/scala/swing/ScrollPane.scala +++ b/src/swing/scala/swing/ScrollPane.scala @@ -3,8 +3,8 @@ package scala.swing import javax.swing.JScrollPane /** - * Can have at most a single child that is put inside a canvas that can be - * scrolled. + * Can have at most a single child component. It display it inside a canvas (the viewport) + * that can be scrolled. * * @see javax.swing.JScrollPane */ @@ -16,8 +16,19 @@ class ScrollPane extends Component with Container { } def contents: Seq[Component] = List(Component.wrapperFor(peer.getViewport.getView.asInstanceOf[javax.swing.JComponent])) + + /** + * Sets the single child. + */ def contents_=(c: Component) { peer.setViewportView(c.peer) } + /** + * The component being displayed in this pane's row header. + * + * If you want to create a row header for lists or tables, you probably + * want to let the row header be a list view with the same row height as + * the viewport component. + */ def rowHeaderView: Option[Component] = Swing.toOption(peer.getRowHeader.getView).map(Component.wrapperFor(_)) def rowHeaderView_=(c: Component) = peer.setRowHeaderView(c.peer) def rowHeaderView_=(c: Option[Component]) = peer.setRowHeaderView(Swing.toNull(c.map(_.peer))) diff --git a/src/swing/scala/swing/Scrollable.scala b/src/swing/scala/swing/Scrollable.scala index 3a2acb8426..06c283ce42 100644 --- a/src/swing/scala/swing/Scrollable.scala +++ b/src/swing/scala/swing/Scrollable.scala @@ -3,7 +3,7 @@ package scala.swing import java.awt.Rectangle /** - * A component that specially suitable for being placed inside a + * A component that is specially suitable for being placed inside a * ScrollPane. * * @see javax.swing.Scrollable diff --git a/src/swing/scala/swing/SequentialContainer.scala b/src/swing/scala/swing/SequentialContainer.scala index a9b663c773..b5cfb65b9b 100644 --- a/src/swing/scala/swing/SequentialContainer.scala +++ b/src/swing/scala/swing/SequentialContainer.scala @@ -3,6 +3,9 @@ package scala.swing import scala.collection.mutable.Buffer object SequentialContainer { + /** + * Utility trait for wrapping sequential containers. + */ trait Wrapper extends Component with SequentialContainer with Container.Wrapper { override val contents: Buffer[Component] = new Content //def contents_=(c: Component*) { contents.clear(); contents ++= c } @@ -10,7 +13,7 @@ object SequentialContainer { } /** - * A container that contains children in a certain order. + * A container that contains children in a specific sequential order. */ trait SequentialContainer extends Container { override def contents: Buffer[Component] diff --git a/src/swing/scala/swing/SimpleGUIApplication.scala b/src/swing/scala/swing/SimpleGUIApplication.scala index 436ba1e10b..2cc5078837 100644 --- a/src/swing/scala/swing/SimpleGUIApplication.scala +++ b/src/swing/scala/swing/SimpleGUIApplication.scala @@ -2,6 +2,10 @@ package scala.swing import javax.swing._ +/** + * Extend this class for most simple UI applications. Clients need to implement the + * top method. Framework intialization is done by this class. + */ abstract class SimpleGUIApplication extends GUIApplication { def top: Frame diff --git a/src/swing/scala/swing/Slider.scala b/src/swing/scala/swing/Slider.scala index b66c37dc8e..36e352bbc3 100644 --- a/src/swing/scala/swing/Slider.scala +++ b/src/swing/scala/swing/Slider.scala @@ -3,6 +3,8 @@ package scala.swing import event._ /** + * Lets users select a value from a given range. Visually, this is represented + * as a draggable knob on a horizontal or vertical bar. * * Fires a ValueChanged event whenever the slider's value changes and * when the knob is released. diff --git a/src/swing/scala/swing/SplitPane.scala b/src/swing/scala/swing/SplitPane.scala index a5026adad7..2cd06e7a5d 100644 --- a/src/swing/scala/swing/SplitPane.scala +++ b/src/swing/scala/swing/SplitPane.scala @@ -4,6 +4,10 @@ import event._ import Swing._ /** + * A container with exactly two children. Arranges them side by side, either + * horizontally or vertically. Displays a draggable divider component between + * them that lets the user adjust the size ratio of the children. + * * @see javax.swing.JSplitPane */ class SplitPane(o: Orientation.Value, left: Component, right: Component) extends Component with Container with Orientable { diff --git a/src/swing/scala/swing/TabbedPane.scala b/src/swing/scala/swing/TabbedPane.scala index e86c1f060c..3661c6988a 100644 --- a/src/swing/scala/swing/TabbedPane.scala +++ b/src/swing/scala/swing/TabbedPane.scala @@ -56,6 +56,10 @@ object TabbedPane { } /** + * Displays the contents of one of several pages at a time. For each page a tab is + * visible at all times. The user can click on one of these tabs to move the + * corresponding page to the front. + * * @see javax.swing.JTabbedPane */ class TabbedPane extends Component with Publisher { @@ -95,6 +99,9 @@ class TabbedPane extends Component with Publisher { */ def tabPlacement(b: Alignment.Value) { peer.setTabPlacement(b.id) } + /** + * The current page selection + */ object selection extends Publisher { def page: Page = pages(index) def page_=(p: Page) { index = p.index } diff --git a/src/swing/scala/swing/Table.scala b/src/swing/scala/swing/Table.scala index fbd4904c5f..15e7128304 100644 --- a/src/swing/scala/swing/Table.scala +++ b/src/swing/scala/swing/Table.scala @@ -26,6 +26,11 @@ object Table { val Row, Column, Cell, None = Value } + /** + * A table item renderer. + * + * @see javax.swing.table.TableCellRenderer + */ abstract class Renderer[-A] { def peer: TableCellRenderer = new TableCellRenderer { def getTableCellRendererComponent(table: JTable, value: AnyRef, isSelected: Boolean, hasFocus: Boolean, row: Int, column: Int) = { @@ -83,6 +88,8 @@ object Table { } /** + * Displays a matrix of items. + * * @see javax.swing.JTable */ class Table extends Component with Scrollable with Publisher { diff --git a/src/swing/scala/swing/ToggleButton.scala b/src/swing/scala/swing/ToggleButton.scala index 0f04aa9f35..cc7827ddb7 100644 --- a/src/swing/scala/swing/ToggleButton.scala +++ b/src/swing/scala/swing/ToggleButton.scala @@ -4,7 +4,8 @@ import javax.swing._ import event._ /** - * A two state button with a push button like UI. Usually used in tool bars. + * A two state button with a push button like user interface. + * Usually used in tool bars. * * @see javax.swing.JToggleButton */ diff --git a/src/swing/scala/swing/UIElement.scala b/src/swing/scala/swing/UIElement.scala index d20bff1ef3..c1a887269b 100644 --- a/src/swing/scala/swing/UIElement.scala +++ b/src/swing/scala/swing/UIElement.scala @@ -3,7 +3,11 @@ package scala.swing import java.awt.{Color, Cursor, Font, Dimension} /** - * The base trait of all user interface elements. + * The base trait of all user interface elements. Subclasses can be divided + * into two groups, top-level elements such as windows and dialogs, and + * Components. + * + * @see java.awt.Component */ trait UIElement extends Proxy { def peer: java.awt.Component -- cgit v1.2.3