Author: rwhitcomb Date: Mon Oct 8 18:24:28 2012 New Revision: 1395705 URL: http://svn.apache.org/viewvc?rev=1395705&view=rev Log: Add a little bit of Javadoc to some classes to aid in basic understanding.
Modified: pivot/branches/2.0.x/core/src/org/apache/pivot/beans/BeanAdapter.java pivot/branches/2.0.x/core/src/org/apache/pivot/json/JSON.java pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/BoxPane.java pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/FillPane.java Modified: pivot/branches/2.0.x/core/src/org/apache/pivot/beans/BeanAdapter.java URL: http://svn.apache.org/viewvc/pivot/branches/2.0.x/core/src/org/apache/pivot/beans/BeanAdapter.java?rev=1395705&r1=1395704&r2=1395705&view=diff ============================================================================== --- pivot/branches/2.0.x/core/src/org/apache/pivot/beans/BeanAdapter.java (original) +++ pivot/branches/2.0.x/core/src/org/apache/pivot/beans/BeanAdapter.java Mon Oct 8 18:24:28 2012 @@ -42,6 +42,16 @@ import org.apache.pivot.util.ListenerLis * Properties may provide multiple setters; the appropriate setter to invoke * is determined by the type of the value being set. If the value is * <tt>null</tt>, the return type of the getter method is used. + * + * <p> Getter methods must be named "getProperty" where "property" is + * the property name. If there is no "get" method, then an "isProperty" + * method can also be used. Setter methods (if present) must be named + * "setProperty". + * + * <p> Getter and setter methods are checked before straight fields + * named "property" in order to support proper data encapsulation. + * And only <code>public</code> and non-<code>static</code> methods + * and fields can be accessed. */ public class BeanAdapter implements Map<String, Object> { /** @@ -171,7 +181,10 @@ public class BeanAdapter implements Map< } /** - * Creates a new bean dictionary. + * Creates a new bean dictionary which can ignore readonly fields + * (that is, straight fields marked as <code>final</code> or bean + * properties where there is a "get" method but no corresponding + * "set" method). * * @param bean * The bean object to wrap. Modified: pivot/branches/2.0.x/core/src/org/apache/pivot/json/JSON.java URL: http://svn.apache.org/viewvc/pivot/branches/2.0.x/core/src/org/apache/pivot/json/JSON.java?rev=1395705&r1=1395704&r2=1395705&view=diff ============================================================================== --- pivot/branches/2.0.x/core/src/org/apache/pivot/json/JSON.java (original) +++ pivot/branches/2.0.x/core/src/org/apache/pivot/json/JSON.java Mon Oct 8 18:24:28 2012 @@ -25,6 +25,19 @@ import org.apache.pivot.collections.adap /** * Contains utility methods for working with JSON or JSON-like data structures. + * + * <p> Special treatment is afforded to {@link java.util.Map java.util.Map} and + * {@link org.apache.pivot.collections.Map org.apache.pivot.collections.Map} objects at any level + * of the hierarchy. Otherwise a {@link BeanAdapter} is used to + * fetch the value from the object. + * + * <p> If, however, the object at a given level is a + * {@link org.apache.pivot.collections.Sequence} then the key + * is assumed to be an integer index into the sequence. + * + * <p> Also, special consideration is given to an object that + * implements the {@link Dictionary} interface. + * */ public class JSON { /** Modified: pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/BoxPane.java URL: http://svn.apache.org/viewvc/pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/BoxPane.java?rev=1395705&r1=1395704&r2=1395705&view=diff ============================================================================== --- pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/BoxPane.java (original) +++ pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/BoxPane.java Mon Oct 8 18:24:28 2012 @@ -43,6 +43,15 @@ import org.apache.pivot.util.ListenerLis * cell, it will retain its natural size, and you can set the * horizontalAlignment and verticalAlignment styles of the BoxPane to, say, * center the button within the cell. + * + * <p> Setting the <code>fill</code> style to true will cause the BoxPane to + * completely fill the space allotted by its container in the direction + * orthogonal to the layout direction. So, for a vertical layout, the + * width will be the width of its container and the children of the BoxPane + * will also be sized accordingly (i.e., full width of the space). And so + * for a horizontal layout, with <code>fill</code> set to true the height + * of the BoxPane will be the height allotted by its container and the + * children of the BoxPane will have their heights set accordingly. */ public class BoxPane extends Container { private static class BoxPaneListenerList extends WTKListenerList<BoxPaneListener> Modified: pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/FillPane.java URL: http://svn.apache.org/viewvc/pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/FillPane.java?rev=1395705&r1=1395704&r2=1395705&view=diff ============================================================================== --- pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/FillPane.java (original) +++ pivot/branches/2.0.x/wtk/src/org/apache/pivot/wtk/FillPane.java Mon Oct 8 18:24:28 2012 @@ -22,12 +22,52 @@ import org.apache.pivot.util.ListenerLis * Container that fills the space it has been given inside its parent * and then arranges its child components in a line, either vertically * or horizontally. + * * <p> This is useful, for instance, as a shortcut to making a one * row and one column {@link TablePane} or {@link GridPane}. Adding - * just one child, such as a {@link ScrollPane}, will allow that child - * to fill the containing area (as opposed to using a {@link BoxPane} which - * will only size itself to the size of its children, which doesn't work - * well with a <tt>ScrollPane</tt>). + * just one child to a FillPane, such as a {@link ScrollPane}, will allow + * that child to fill the containing area (as opposed to using a {@link BoxPane} + * which will only size itself to the size of its children, which doesn't always + * work well with a <tt>ScrollPane</tt>). + * + * <p> The <b>n</b> children of a FillPane will be given 1/n of the total space available, + * depending on the orientation. For vertical, each child's height will be 1/n + * of the total height, and for horizontal each child's width will be 1/n of the + * total width. The children will always stretch to the full width / height of + * the orthogonal direction. + * + * <p> Here is an example: for a horizontal FillPane with three buttons as + * children: + * <pre>+--------------------------------------------------+ +|+---------------++--------------++---------------+| +|| || || || +|| || || || +|| || || || +|| Button 1 || Button 2 || Button 3 || +|| || || || +|| || || || +|| || || || +|+---------------++--------------++---------------+| ++--------------------------------------------------+</pre> + * <p> And here is a vertical FillPane with three Button children: + * <pre>+--------------------------------------------------+ +|+------------------------------------------------+| +|| || +|| Button 1 || +|| || +|+------------------------------------------------+| +|+------------------------------------------------+| +|| || +|| Button 2 || +|| || +|+------------------------------------------------+| +|+------------------------------------------------+| +|| || +|| Button 3 || +|| || +|+------------------------------------------------+| ++--------------------------------------------------+</pre> + * */ public class FillPane extends Container { private static class FillPaneListenerList extends WTKListenerList<FillPaneListener>